🆕 Webhook 공통 규격

그리팅은 채용 과정의 주요 이벤트를 외부 시스템으로 전달하는 웹훅을 제공합니다.

• 전달 방식 2가지

  • Pull (Event Feed API): 상시 수신 서버 없이 주기적으로 이벤트를 조회 - 배치

  • Push (Webhook): 등록한 endpoint로 그리팅이 HTTP POST - 실시간, 수신 서버 필요

• 두 방식은 같은 이벤트 저장소를 보므로 eventId도 본문도 완전히 동일합니다. 함께 사용하면 Push로 놓친 이벤트를 Pull로 복구할 수 있습니다.

• Business 플랜 전용 기능입니다. 플랜이 해지·다운그레이드되면 전송이 중단됩니다.

모든 웹훅 payload는 아래 공통 봉투로 감싸집니다. 이벤트별 상세는 data에 담깁니다.

공통 예시

알 수 없는 eventType은 무시하도록 구현하세요.

테스트 발송(WEBHOOK_TEST)과 앞으로 추가될 이벤트가 같은 endpoint로 도착합니다.

모르는 종류를 오류로 처리하면 새 이벤트가 추가될 때마다 수신이 실패합니다.

data의 필드는 값이 없으면 키 자체가 빠집니다. 항상 존재한다고 가정하지 말고 없을 때를 처리하세요.

Open API 문서를 참조해주세요.

등록한 endpoint로 POST 요청을 보냅니다.

실패 시 지수 백오프로 최대 7회(누적 약 15시간) 재시도합니다.

응답 코드에 따라 동작이 다릅니다.

연속 실패가 7회에 이르면 해당 웹훅이 자동으로 중단됩니다.

• 워크스페이스 설정에서 중단 상태와 최근 실패 원인(응답 코드·오류 메시지·시각)을 확인하고, 원인 해결 후 재활성화할 수 있습니다.

• 한 번이라도 성공하면 연속 실패 카운트는 0으로 초기화됩니다.

• 플랜 제한으로 중단된 웹훅은 화면에서 재활성화할 수 없으며, Business 플랜으로 전환하면 자동 복구됩니다.

• 별도 이메일 알림은 제공하지 않습니다. 설정 화면을 정기적으로 확인하거나 자체 모니터링을 두는 것을 권장합니다.

같은 지원자의 이벤트는 발생 순서대로 전달됩니다.

• 앞선 이벤트 전달이 실패하면 재시도가 끝날 때까지 그 지원자의 다음 이벤트는 대기합니다. 다른 지원자에는 영향이 없습니다.

• 단, 재시도가 모두 소진되면 다음 이벤트로 진행하므로 그 시점에는 순서가 어긋날 수 있습니다.

같은 이벤트가 두 번 이상 도착할 수 있습니다.

수신 측 2xx가 네트워크 문제로 그리팅에 닿지 못하면 재전송되기 때문입니다. eventId로 중복을 제거하세요.

if seen.exists(event["eventId"]):
    return "", 200          # 이미 처리함 — 성공으로 응답
seen.put(event["eventId"])  # 처리 후 기록
process(event)

발생 후 24시간이 지난 이벤트는 Push되지 않습니다.

지난 상태가 뒤늦게 도착하면 수신 측 자동화가 과거 상태로 되돌아갈 수 있기 때문입니다. 해당 이벤트는 Pull(Event Feed)로는 그대로 조회됩니다.

합격 처리 시 APPLICANT_PROCESS_MOVED(movedType: PASS)와 APPLICANT_PASSED가 함께 발생합니다.

합격 취소도 APPLICANT_PROCESS_MOVED(movedType: PASS_CANCELED) + APPLICANT_PASS_REVOKED 2건입니다.

중복이 아니라 별개 이벤트이므로 두 종류를 모두 구독한 경우 각각 처리하세요. 한 번만 처리하려면 둘 중 하나만 구독하면 됩니다.

전송 위·변조 여부를 확인할 수 있도록, 웹훅 구독마다 서명 secret이 발급되고 모든 요청에 서명이 첨부됩니다.

검증은 선택이므로 불필요시 인증을 무시하실 수 있습니다.

• 헤더 형식: X-Greeting-Signature: sha256 <hex_digest> - sha256과 hex 사이는 공백입니다.

• 계산식: HMAC_SHA256(secret, 요청 raw body)를 소문자 hex로

• 반드시 파싱 전 raw body 바이트로 검증하세요. 파싱 후 재직렬화하면 공백·필드 순서가 달라져 서명이 일치하지 않습니다.

• secret은 whsec_로 시작합니다. 웹훅마다 서로 다른 secret이 발급되므로, 수신 URL이 같더라도 각각의 secret으로 검증해야 합니다.

의사코드

Node.js (Express)

Python (Flask)

Java (Spring Boot)

secret은 웹훅 생성·재발급 시 딱 한 번만 전체가 표시되며, 이후에는 마스킹된 값만 조회됩니다. 안전한 곳(환경변수·비밀 저장소)에 보관하세요.재발급 시 이전 secret은 즉시 무효화되므로, 수신 서버의 secret을 교체하기 전까지 서명 검증이 실패합니다. 무중단으로 교체하려면 두 값을 모두 허용하도록 수신 서버를 먼저 배포한 뒤 재발급하고, 이후 옛 값을 제거하세요.

설정 화면에서 테스트 발송을 눌러 수신 URL 연결과 서명 검증을 즉시 확인할 수 있습니다. 응답 코드가 그 자리에서 표시됩니다.

예시

테스트 발송은 연결·서명 확인용입니다.

이벤트별 payload 파싱까지 검증하려면 개발용 공고에 실제 지원자를 등록해 실제 이벤트를 받아보세요.

• 워크스페이스 설정 > 웹훅 페이지에서 관리합니다.

• 구독 1건 = 이름 + 수신 URL + secret + 구독할 이벤트 집합. 하나의 URL로 여러 이벤트를 받고, 수신 측에서 eventType으로 분기합니다.

• 수신 URL은 https만 등록할 수 있으며, 워크스페이스당 최대 5개까지 등록됩니다.

• 웹훅마다 on/off 토글로 켜고 끌 수 있습니다.

• 같은 이벤트를 여러 웹훅이 받을 수 있습니다(fan-out). 각 웹훅은 독립적으로 발송·재시도·순서 보장됩니다.

• 설정 변경은 반영까지 최대 30초가 걸릴 수 있습니다.

• Pull(Event Feed)만 사용하는 경우 수신 URL 등록 없이 read:events 스코프 Open API 키만으로 이용할 수 있습니다. 설정 페이지에서 현재 수집 상태를 확인할 수 있습니다.

• 관리 권한: 워크스페이스의 외부 인터페이스 관리 권한이 필요합니다. 기본 제공 역할 중 소유자·관리자가 이 권한을 가지며, 일반 멤버에게는 없습니다. Open API 키 관리와 같은 권한입니다.

기본은 "웹훅 1개에 전체 이벤트"를 권장합니다. 용도가 확실히 다를 때만 나누세요(예: 합격 → 인사시스템, 지원자 등록 → 슬랙).짝을 이루는 이벤트는 같은 웹훅에 묶으세요. 합격(APPLICANT_PASSED)과 합격 취소(APPLICANT_PASS_REVOKED), 불합격(APPLICANT_REJECTED)과 불합격 취소(APPLICANT_REJECTION_REVOKED)를 서로 다른 웹훅으로 갈라 놓으면, 한쪽만 실패했을 때 수신 시스템의 지원자 상태가 실제와 어긋납니다.

신규 웹훅 도입 전에 등록된 합격자 웹훅은 당분간 그대로 동작하지만, 설정 화면에서 추가·수정은 제공되지 않고 삭제만 가능합니다.

• 서명·재시도·상태 관리가 없고 payload 형식도 다릅니다.

• 새 웹훅(APPLICANT_PASSED)으로 전환한 뒤 이전 방식 웹훅을 삭제하세요. 두 방식이 동시에 동작하면 합격 알림을 중복 수신합니다. 두 방식은 eventId를 공유하지 않아 자동으로 걸러지지 않습니다.