메인 콘텐츠로 건너뛰기
알림 webhook은 팀의 알림을 여러분이 소유한 HTTPS endpoint로 전송합니다. 온콜 도구, 티켓 대기열 또는 자체 운영 대시보드에 알림을 전달하는 데 사용하세요. 알림 webhook은 인증 webhook과 별개입니다. 인증 webhook은 세션, 엔티티 및 거래 결과를 애플리케이션으로 전송합니다. 알림 webhook은 검토가 필요한 인증, 실패한 결제, 서비스 장애처럼 주의가 필요한 상황을 팀에 알립니다. 알림 webhook에는 고유한 페이로드, 서명 비밀, 서명 및 재시도 일정이 있습니다.

대상 설정

알림 webhook은 API가 아니라 Business Console에서 구성합니다. 조직 설정을 관리할 수 있는 멤버가 webhook 대상을 추가, 변경 및 테스트할 수 있습니다.
1

대상 추가

조직 설정 > 팀 알림에서 endpoint URL을 입력하여 알림 webhook 대상을 추가합니다. URL은 https://를 사용해야 하며 공개 주소로 해석되어야 합니다.
2

서명 비밀 저장

Didit은 whsec_로 시작하는 전체 서명 비밀을 한 번만 표시합니다. 지금 저장하세요. 이후 콘솔에는 마지막 네 자리만 표시됩니다.
3

알림 라우팅

대상을 추가해도 아직 아무것도 전송되지 않습니다. 수신하려는 알림의 라우팅 규칙에 대상을 추가하세요.
4

테스트 전송

테스트 전송을 클릭하여 alert.test 알림을 보내고, endpoint가 이를 수락하는지 확인하세요.
조직은 팀 알림에 최대 25개의 webhook 대상을 가질 수 있습니다. 프로덕션 활동만 webhook 대상으로 전송됩니다. 샌드박스 인증, 기업 확인(KYB), 거래 및 AML 히트에 대한 알림은 대상으로 절대 전송되지 않습니다.

알림 유형

페이로드

모든 알림은 JSON 본문을 가진 POST 요청입니다. Didit은 키를 정렬한 압축된 JSON으로 본문을 전송합니다. 이 예시는 읽기 쉽도록 포맷되어 있습니다.
data에는 항상 다음이 포함됩니다.
  • event: 이벤트 키입니다. 예: session_in_review.
  • label과 value: 알림의 대상을 나타냅니다. 예: Session과 #1042.
일부 알림 유형은 data에 키를 추가합니다.
  • alert.billing.autorefill_failed는 paused를 추가합니다. 이는 카드를 업데이트할 때까지 자동 충전이 일시 중지되었는지를 나타내는 불리언 값으로, 일시 중지된 경우 true입니다.
  • alert.service.degraded와 alert.service.recovered는 service, status, incident_id, service_name, state, affected, country_name, started_at, resolved_at, duration_minutes, title, body를 추가합니다. status는 alert.service.degraded에서 degraded 또는 down이고, alert.service.recovered에서는 recovered입니다. service는 GET /v3/status/의 서비스 키를 사용하며, incident_id는 그곳의 인시던트 id와 일치합니다.
알림에는 최종 사용자의 개인 정보나 문서 데이터가 절대 포함되지 않습니다. 세션, 거래 또는 기타 항목은 번호로 식별되며, 콘솔의 해당 항목으로 연결되는 링크가 제공됩니다. 인식하지 못하는 webhook_type 값과 data 키는 무시하세요. 그래야 새로운 값이나 키가 추가되어도 endpoint가 중단되지 않습니다.

요청 헤더

Verify the signature

X-Signature-V2는 <X-Timestamp>.<raw body> 문자열에 대해 대상의 서명용 시크릿을 키로 하여 계산한 HMAC-SHA256 값을 16진수로 인코딩한 것입니다.
  • Didit이 표시한 전체 시크릿을 whsec_ 접두사를 포함하여 그대로 사용하십시오.
  • 요청을 받은 그대로의 원본 바이트에 대해 서명을 검증하십시오. JSON을 파싱했다가 다시 직렬화하면 바이트가 바뀌어 검증이 실패할 수 있습니다.
  • 서명을 비교할 때는 상수 시간 비교를 사용하십시오.
  • X-Timestamp가 현재 시각과 5분을 초과하여 차이 나는 요청은 거부하십시오. Didit은 재시도를 포함한 모든 전송 시도마다 새 타임스탬프로 서명하므로, 이 허용 범위 때문에 정상적인 재시도가 거부되는 일은 없습니다.
  • 검증에 실패하면 400으로 응답하십시오. 401, 403, 404 또는 410 응답은 대상을 다시 연결해야 하는 상태로 표시합니다(재시도 참조).
알림 webhook은 검증 webhook과 같은 방식으로 서명되지 않습니다. 헤더 이름도 X-Signature-V2이지만, 서명 대상 문자열이 다릅니다. 또한 알림 webhook은 X-Signature 또는 X-Signature-Simple 헤더를 보내지 않습니다. 검증 webhook용 검증기를 재사용하지 마십시오.

Node.js (Express)

Python (Flask)

서명 시크릿 교체

팀 알림에서 대상의 시크릿을 교체합니다. Didit은 새 시크릿을 한 번만 표시하며, 교체 이후의 모든 전송 시도에 이 시크릿으로 서명합니다. 교체 이전에 생성된 알림의 재시도도 포함됩니다. 이전 시크릿은 즉시 사용할 수 없게 됩니다. 겹치는 기간은 없으며, 이전 시크릿으로 만든 서명이 담긴 헤더도 더 이상 전송되지 않습니다. 시크릿을 교체하면 바로 endpoint에 새 시크릿을 배포하십시오.

재시도

Didit은 2xx 응답을 전송 완료로 간주합니다. 각 시도는 응답을 최대 5초 동안 기다리며, 리다이렉트를 따르지 않습니다. Didit은 시간 초과, 연결 실패, 5xx 응답, 408, 425 또는 429 응답이 발생하면 알림을 재시도합니다. 재시도는 최대 5회이며, 약 24시간에 걸쳐 진행됩니다. 그 밖의 모든 응답은 최종 응답이며, 3xx와 그 밖의 4xx 응답도 포함됩니다. 테스트 전송으로 보낸 요청은 한 번만 시도되며, 재시도하지 않습니다. 401, 403, 404 또는 410 응답도 대상을 다시 연결해야 하는 상태로 표시합니다. 콘솔에는 다시 연결 상태로 나타납니다. Didit이 전송할 때 URL이 사설 주소나 그 밖의 차단된 주소로 확인되는 경우에도 같은 상태가 됩니다. Didit은 해당 대상으로 새 알림을 계속 전송하며, 다음 전송이 성공하거나 URL을 업데이트하면 다시 활성 상태가 됩니다. 팀 알림의 최근 알림에서는 각 전송과 그 결과를 확인할 수 있으며, 실패한 전송은 여기서 다시 시도할 수 있습니다.

관련 문서

  • 검증 webhook: 애플리케이션의 세션, 엔터티 및 거래 결과를 다룹니다.
  • 서비스 상태: alert.service.degraded 및 alert.service.recovered 이벤트의 기반이 되는 공개 피드입니다.
  • 수동 검토: 검토 중인 인증을 처리하는 방법입니다.
마지막 수정일 2026년 11월 7일