라운드 Webhook 개요

1. Webhook 이란

라운드 Webhook을 통해 라운드 상에서 이벤트 발생 시 등록하신 callback url 로 알림을 받아보실 수 있습니다.

2. Webhook 활용

지원자의 채용 단계 변경, 평가 완료, 면접 일정 확정 등 주요 이벤트 발생 시 등록하신 callback url로 실시간 알림을 받아보실 수 있습니다.

3. Webhook 연동

Webhook은 API를 통해 등록, 수정, 삭제할 수 있습니다.

기능	엔드포인트
목록 조회	GET /v1/webhooks
상세 조회	GET /v1/webhooks/{code}
등록	POST /v1/webhooks
수정	PATCH /v1/webhooks/{code}
삭제	DELETE /v1/webhooks/{code}

상세한 API 명세는 Webhook API 문서를 참조하세요.

현재 지원 가능한 이벤트 목록은 아래와 같습니다.

타입	설명
candidate_stage_changed	지원자의 채용 단계가 변경될 때
candidate_pass	지원자가 합격 단계로 이동할 때
feedback_created	평가가 생성될 때
feedback_completed	평가가 완료될 때
interview_scheduled	면접 일정이 확정될 때

4. 재전송 정책

웹훅 전송이 실패할 경우 (HTTP 200 응답이 아닌 경우), 라운드는 자동으로 재전송을 시도합니다.

시도	대기 시간
1차 재시도	10초 후
2차 재시도	30초 후
3차 재시도	90초 후
4차 재시도	270초 (4.5분) 후

최초 전송 포함 최대 5회까지 전송을 시도하며, 모든 시도가 실패할 경우 해당 웹훅 이벤트는 전송되지 않습니다. callback url이 정상적으로 응답하는지 확인해 주세요.

5. Payload 형태

웹훅 요청은 다음과 같은 형태로 전송됩니다.

{
  "action": "candidate_pass",
  "payload": {
    // 이벤트별 데이터
  }
}

6. 서명 검증

callback url과 함께 signing key를 등록하시면 웹훅 요청이 라운드에서 발송된 것인지 검증할 수 있습니다.

signing key를 등록하실 경우 아래와 같이 header에 서명이 포함되어 전송됩니다.

Round-Webhook-Signature: t=1234567890,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

• t: 요청 발송 시점의 Unix timestamp

• v1: HMAC-SHA256 서명값

1) 검증 방법

서명은 {timestamp}.{payload} 형태의 문자열을 signing key로 HMAC-SHA256 해시한 값입니다.

Ruby

timestamp = header['Round-Webhook-Signature'].match(/t=(\d+)/)[1]
received_signature = header['Round-Webhook-Signature'].match(/v1=([a-f0-9]+)/)[1]

expected_signature = OpenSSL::HMAC.hexdigest('SHA256', signing_key, "#{timestamp}.#{payload}")

if expected_signature == received_signature
  # 유효한 요청
end

Python

import hmac
import hashlib

expected_signature = hmac.new(
    signing_key.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if expected_signature == received_signature:
    # 유효한 요청

2) Replay Attack 방지

timestamp를 확인하여 오래된 요청을 거부할 수 있습니다. 일반적으로 5분 이내의 요청만 허용하는 것을 권장합니다.

if Time.now.to_i - timestamp.to_i > 300
  # 5분 초과된 요청 거부
end