고객 웹훅

고객 웹훅은 정준 작업 결과를 사용자가 관리하는 HTTPS 엔드포인트로 전달합니다. 설정 → 웹훅 또는 POST /v1/webhooks로 구독을 생성합니다. 서명 비밀은 생성 직후 한 번만 표시됩니다.

전달 계약

모든 요청의 JSON 본문에는 schema_version, event_id, event_type, occurred_at과 안전한 작업 식별자를 담은 data가 포함됩니다.

본문을 수락하기 전에 다음 헤더를 검증하세요.

• Ankk-Webhook-Id: 재시도에도 유지되는 전달 ID이며 중복 제거 키입니다.
• Ankk-Webhook-Event: 이벤트 종류입니다.
• Ankk-Webhook-Timestamp: 서명에 사용한 ISO 시각입니다.
• Ankk-Webhook-Signature: v1= 접두사가 붙은 HMAC-SHA256 16진 서명입니다.

서명 비밀로 <timestamp>.<가공하지 않은 요청 본문>의 HMAC을 계산하고 상수 시간 비교를 수행합니다. 수신 시스템이 이벤트를 안전하게 저장한 뒤에만 2xx를 반환하세요.

재시도와 안전성

전달은 최소 한 번(at-least-once) 방식입니다. Ankk Threads는 실패를 백오프로 재시도하고 lease가 만료된 작업을 다른 실행자가 복구하며, 8회 실패한 전달은 dead-letter 상태로 이동합니다. 수신자는 전달 ID로 중복을 제거해야 합니다.

대상은 공개 HTTPS 주소여야 합니다. loopback, 사설 IP, link-local 주소와 인증 정보가 포함된 URL은 거부됩니다. payload에는 자격 증명, 이메일 주소, 원본 공급자 응답, 자유 형식 공급자 오류 메시지가 포함되지 않습니다.

GET /v1/webhook-deliveries 또는 ankk-threads webhooks deliveries로 정준 전달 결과를 확인할 수 있습니다.