🆕 Webhook 공통 규격

모든 웹훅에 공통으로 적용되는 규격입니다. 개별 이벤트의 data 필드와 예시는 각 이벤트 문서를 참고하세요.

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

  • 전달 방식 2가지

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

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

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

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

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

필드

타입

필수 여부

설명

eventId

String

필수

이벤트 고유 식별자(UUID). 재시도 시에도 동일 — 중복 수신 제거(dedupe) 키로 사용하세요

eventType

Enum

필수

이벤트 종류 (12종 중 하나, 또는 테스트 발송의 WEBHOOK_TEST)

occurredAt

String

필수

이벤트 발생 시각. 항상 UTC로 보내며 Z로 끝납니다 (예: 2026-07-24T01:15:30Z). 로컬 시간대가 필요하면 수신 측에서 변환하세요

workspaceId

Integer

필수

워크스페이스 고유 id 값입니다

data

Object

필수

이벤트별 상세 payload (각 이벤트 문서 참조)

공통 예시

JSON

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

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

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

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

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

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

헤더

값

설명

Content-Type

application/json

X-Greeting-Event-Id

이벤트 고유 id

본문의 eventId와 같은 값입니다. 중복 제거용

X-Greeting-Signature

sha256 <hex>

HMAC-SHA256 서명 (아래 참조)

규칙

내용

성공 = HTTP 2xx

그 외 응답·타임아웃·네트워크 오류는 모두 실패로 간주합니다

10초 안에 응답

10초 내에 응답이 없으면 실패로 처리하고 재시도합니다

먼저 받고, 나중에 처리

무거운 작업(외부 API 호출, DB 대량 갱신 등)은 큐에 넣고 즉시 2xx를 반환하세요. 처리를 끝낸 뒤 응답하면 불필요한 재시도가 발생합니다

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

시도

1회

2회

3회

4회

5회

6회

7회

직전 실패 후 대기

즉시

1분

15분

1시간

2시간

4시간

8시간

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

응답

동작

이유

2xx

성공, 종료

—

400 401 403 404 405 410 422

2회에서 조기 종료

다시 보내도 결과가 같은 수신 URL·인증·구현 설정 문제입니다. 설정을 확인하세요

408 429 5xx, 무응답·타임아웃

전체 7회 일정대로 재시도

시간이 지나면 풀릴 수 있는 일시적 장애로 봅니다

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

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

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

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

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

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

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

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

면접 이벤트(확정·일정 변경·장소 변경·취소)는 도착 순서가 실제 발생 순서와 다를 수 있습니다.

  • 최종 상태는 data.status로 판단하세요.

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

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

Plaintext
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으로 검증해야 합니다.

의사코드

Groovy

Node.js (Express)

JavaScript

Python (Flask)

Python

Java (Spring Boot)

Java

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

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

항목

내용

eventType

WEBHOOK_TEST — 12종 이벤트와 구분되는 전용 값입니다

서명

실제 발송과 동일하게 첨부됩니다 (서명 검증 로직을 그대로 확인할 수 있습니다)

데이터

지원자·평가·면접 식별자를 담지 않습니다. 조회 API로 이어질 값이 없습니다

이력

이벤트로 적재되지 않습니다 — Pull(Event Feed)에서 조회되지 않고 재시도·실패 집계에도 잡히지 않습니다

비활성 웹훅

꺼져 있거나 중단된 웹훅도 테스트할 수 있습니다 (고친 뒤 확인하는 용도)

설정 반영

설정 변경이 반영되기까지 최대 30초가 걸릴 수 있지만, 테스트 발송은 기다리지 않고 즉시 전송됩니다

예시

JSON

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

이벤트별 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)를 서로 다른 웹훅으로 갈라 놓으면, 한쪽만 실패했을 때 수신 시스템의 지원자 상태가 실제와 어긋납니다.

면접 이벤트 4종(확정·일정 변경·장소 변경·취소)도 같은 웹훅에 묶으세요. 확정은 받고 취소를 놓치면 이미 취소된 면접이 수신 시스템에 남습니다.

상황

결과

Business → 하위 플랜 / 해지

모든 웹훅이 자동 중단됩니다.설정 자체는 남아 있습니다

하위 플랜 → Business

자동으로 재개됩니다. 중단 전에 켜져 있던 웹훅만 다시 켜집니다

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

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

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

항목

값

요금제

Business 플랜 전용

워크스페이스당 웹훅 수

최대 5개

수신 URL

https 전용

수신 서버 응답 제한 시간

10초

성공 판정

HTTP 2xx

재시도

최대 7회 (약 15시간). 재시도 무의미한 4xx는 2회

자동 비활성화

연속 7회 실패

Push 시효

발생 후 24시간 (초과 시 Pull로만 제공)

이벤트 보관 기간

7일

Event Feed 페이지 크기

기본 50, 최대 100

설정 반영 지연

최대 30초 (테스트 발송은 즉시)

전달 보장

at-least-once (중복 가능, eventId로 제거)

순서 보장

같은 지원자 단위

과거 데이터 소급 제공

지원하지 않음 (설정 시점 이후만)

발송 이력 조회

최근 7일 (웹훅별, 설정 화면)