09. 웹훅 명세서 v1

JEDI 거버넌스 — 웹훅 명세서 v1

1. 웹훅 등록 (POST /v1/webhooks)

{
  "url": "https://client.example.com/jedi-webhook",
  "events": ["approval.pending", "approval.approved", "approval.rejected", "request.completed"],
  "secret": "client가 생성한 서명 검증용 비밀키"
}

2. 서명 검증 (X-JEDI-Signature)

모든 웹훅 요청에는 X-JEDI-Signature 헤더가 포함됩니다.

X-JEDI-Signature: sha256=<HMAC_SHA256(secret, raw_request_body)>

클라이언트는 secret으로 HMAC-SHA256을 계산하여 헤더와 검증해야 하며, 불일치 시 요청을 즉시 폐기합니다.

3. 재전송 (Retry) & Dead-Letter

• 클라이언트가 2xx 응답을 반환하지 않으면 최대 5회 지수 백오프 재전송 (즉시 → 1분 → 5분 → 30분 → 2시간).
• 5회 수신 실패 시 Dead-Letter 큐로 이동하며 GET /v1/webhooks/dead-letter로 조회 가능.