전달

재시도

ZeroTalk는 모든 웹훅을 내부 큐를 거쳐 전달하며, 결과적으로 at-least-once입니다. 이벤트를 큐에 넣은 뒤 보통 1초 안에(부하가 걸리면 드물게 수십 초 뒤) 첫 전달이 일어납니다. 전달은 두 단계로 재시도합니다.

1. 전달 시도: 한 번의 전달 사이클에서 429, 5xx, 연결 오류(타임아웃·연결 실패)를 받으면 최대 3회 시도합니다. 시도 사이에 1초, 2초를 기다립니다.
2. 재전달: 한 사이클이 실패하면 이벤트를 큐에 남겨 이벤트 접수 시점부터 최대 약 24시간 동안 다시 시도합니다.

성공 판정은 2xx 응답입니다. 4xx(429 제외)를 받으면 한 사이클 안에서는 재시도 없이 멈춥니다.

한 사이클이 실패하면 실패 유형(4xx·5xx·네트워크 오류)과 관계없이 같은 규칙으로 큐에서 다시 시도합니다. 처음 몇 번은 1초에서 2분까지 늘어나는 짧은 간격으로, 그 뒤에는 약 30분 간격으로 시도합니다. 이벤트 접수 시점부터 약 24시간이 지나면 폐기합니다. 잘못된 페이로드 때문에 4xx가 계속 나는 이벤트도 같은 규칙으로 폐기하므로 무한히 재시도하지 않습니다.

응답 코드가 404이면 존재하지 않는 경로로 보고, 재전달하지 않고 바로 폐기합니다. 이 경우에도 이벤트의 첫 시도에서 받은 404는 자동 비활성화의 연속 실패 횟수에 들어갑니다.

중복 이벤트 걸러 내기

같은 이벤트가 두 번 이상 도착할 수 있으므로 수신 서버에서 멱등 처리를 하세요. 모든 요청 본문에는 이벤트마다 고유한 event_id가 들어 있고, 같은 이벤트를 재전송해도 이 값은 바뀌지 않습니다. 처리한 event_id를 저장해 두고, 이미 처리한 값이 오면 건너뛰세요. 요청 헤더로 전달하는 delivery-id는 없습니다. 서명용 헤더 X-Webhook-Timestamp는 재전송할 때마다 갱신되므로 멱등 키로 쓰지 마세요.

ZeroTalk도 10분 안에는 같은 이벤트의 중복 발송을 억제하려고 하지만, 보장하지는 않습니다. 그 밖의 경우에는 재발송될 수 있습니다.

타임아웃

• 개별 HTTP 요청: 10초
• 전체 전달(재시도 포함) 컨텍스트: 20초

수신 endpoint는 가능한 한 빨리(권장 5초 이내) 2xx로 응답하고, 무거운 처리는 자체 큐에 넣어 비동기로 처리하세요.

순서 보장

웹훅 전달 순서는 보장되지 않습니다. 전달 시도와 재전달 때문에 나중에 발생한 이벤트가 먼저 도착할 수 있고, 전역 순번도 없습니다.

• 메시지: 한 채널 안 순서는 data.seq(생성 시 부여되는 채널 순번)로 판단하세요.
• 채널 이벤트: data.version(채널 집계 버전)이 대략적인 순서를 주지만, 한 번의 변경에서 여러 이벤트가 같은 version으로 나올 수 있어(예: 종료 시 배정 해제 + 종료) 완전한 단일 순서 키는 아닙니다. 정확한 현재 상태가 필요하면 GET /channels/{id}(channels:read scope의 PAT 필요)로 다시 조회하세요.
• data.created_at은 *.created 이벤트에만 있어 범용 정렬 키로 쓸 수 없고, 채널을 가로지르는 절대 순서는 봉투 timestamp(전송 시각의 근사치)로만 대략 가늠할 수 있습니다.

출발지 IP

ZeroTalk는 웹훅을 고정된 출발지 IP에서 보낸다고 보장하지 않습니다. 인프라에 따라 IP가 바뀔 수 있으므로, 수신 endpoint는 IP 허용목록이 아니라 서명 검증으로 요청을 인증하세요.

자동 비활성화

연속 10회 실패하면 웹훅 상태가 error로 바뀌고 정상 송신이 중단됩니다. 이 횟수는 각 이벤트의 첫 전달 시도만 셉니다. 첫 시도는 큐를 거칩니다(재시도 참고). 이어지는 재전달의 실패는 세지 않으므로 재전달이 임계 도달을 앞당기지 않습니다. 비활성 기간에 보류됐다가 재활성화 후 처음 전달되는 이벤트의 첫 시도는 횟수에 들어갑니다. 전달에 성공(2xx)하면 횟수가 0으로 돌아갑니다.

웹훅이 error가 되면 워크스페이스 관리자(owner/admin)에게 이메일과 대시보드 실시간 알림을 보냅니다. 단, 한 번도 성공한 적 없는(설정 중인) 웹훅은 알리지 않고, 같은 웹훅에 대한 알림은 24시간에 한 번으로 제한합니다.

복구하기

error 상태의 웹훅은 아래 두 방법으로 active가 됩니다.

• 자동 복구: ZeroTalk가 일정 간격마다 새로 발생한 실제 이벤트 한 건을 시험 삼아 전달합니다. 시험 전달이 2xx를 받으면 웹훅이 active로 돌아오고 실패 횟수(failure_count)가 0이 됩니다. 첫 시험 전달은 비활성화되고 빠르면 5분 뒤에 일어납니다. 시험할 때마다 간격이 5분, 10분, 20분, 40분, 80분, 160분, 320분으로 두 배씩 늘고, 그 뒤에는 6시간입니다. 시험 전달이 실패하면 그 이벤트는 재전달하지 않고 폐기합니다. 비활성화 알림을 보낸 웹훅이 비활성화 후 24시간 안에 복구되면 같은 관리자에게 복구 알림도 보냅니다.
• 수동 재활성화: 사유를 확인하고 endpoint를 고친 뒤 대시보드 토글 또는 PAT API의 POST /outbound-webhooks/{id}/toggle로 다시 활성화합니다. 재활성화하면 failure_count가 0이 됩니다. 자동 복구를 기다리지 않고 바로 복구하고 싶을 때 사용하세요.

inactive(사람이 일시 중지한 상태)는 자동 복구 대상이 아닙니다. 직접 다시 활성화해야 합니다.

비활성 기간의 이벤트

비활성(error 또는 inactive)이 되기 전에 큐에 들어가 있던 미전달분은 곧바로 폐기하지 않고 보류합니다. 이벤트 접수 시점부터 24시간 안에 웹훅이 다시 활성화되면 보류분을 전달합니다. 반면 비활성화된 뒤에 새로 발생한 이벤트는 전송하지 않고 보존하지도 않습니다. 위에서 설명한 시험 전달용 이벤트 한 건만 예외입니다. 알림을 받으면 가능한 한 빨리 endpoint를 고치고 웹훅을 활성화하세요.

에코 correlation

Public API로 답장을 보내는 콘솔에 한정된 주의 사항입니다.

상담원이 POST /channels/{id}/messages로 보낸 답장은 message.created 웹훅으로 다시 도착합니다. 그런데 웹훅 페이로드에는 전송 시 보낸 client_request_id가 없습니다. 따라서 다음과 같이 message_id로 상관(correlate) 하세요.

1. 전송 응답의 data.id(새 메시지 id)를 짧게 유지되는 집합에 저장합니다.
2. message.created 웹훅이 도착하면 data.message_id가 그 집합에 있는지 확인합니다.
3. 있으면 자신이 보낸 메시지의 에코이므로 이미 렌더된 것으로 취급해 중복 렌더를 피합니다.

client_request_id는 전송 멱등성(같은 키로 재시도하면 원본 반환) 용도일 뿐, 웹훅 상관 키가 아닙니다.

전달 로그

대시보드의 채팅 설정 → 연동 / 개발 → Webhook 설정에서 해당 웹훅의 이력을 클릭하면 배달 이력 창이 열립니다. 이벤트마다 성공·실패 여부, 응답코드, 소요시간, 오류 메시지를 확인할 수 있습니다.

PAT로 웹훅을 등록했다면 GET /outbound-webhooks/{id}/delivery-logs로도 조회할 수 있습니다.

웹훅이 도착하지 않을 때

아래 순서로 확인하세요.

1. 웹훅 상태를 확인합니다. Webhook 설정 목록에서 상태가 오류(error)나 비활성(inactive)이면 정상 송신이 중단된 상태입니다. 복구 방법은 자동 비활성화를 참고하세요.
2. 전달 로그를 확인합니다. 이력에 실패 기록이 있다면 응답코드와 오류를 보세요. 응답코드가 404이면 URL의 경로가 맞는지 확인하세요. 404는 재전달하지 않습니다. 오류가 타임아웃이면 수신 endpoint가 10초 안에 응답하는지 확인하세요(타임아웃 참고).
3. 로그가 비어 있다면 구독 설정을 확인합니다. 웹훅 수정 화면에서 구독 이벤트에 원하는 이벤트가 들어 있는지 확인하세요. 전달 조건을 설정했다면 조건에 맞는 대화의 이벤트만 전송합니다.
4. 전송 제외 대상인지 확인합니다. 고객 상담 채널(user_chat)이 아닌 내부 채널의 이벤트와 상담원의 내부 메모는 웹훅으로 보내지 않습니다(이벤트 참고).
5. 수신 서버의 서명 검증을 확인합니다. 검증에 실패했다고 비-2xx로 응답하면 웹훅 입장에서는 전달 실패입니다. 서명이 맞지 않을 때를 참고하세요.

웹훅 관리 API

웹훅은 대시보드 UI 또는 PAT API로 관리합니다. 외부 BFF·서버에서 토큰으로 관리하려면 Outbound 웹훅 관리 API(webhooks:read/webhooks:write)를 사용하세요. 아래 표의 관리 API는 그와 별개로, 대시보드 인증(JWT)과 integration:manage 권한이 필요한 내부 경로입니다.

Method	Path	설명
POST	/workspaces/me/webhooks	생성
GET	/workspaces/me/webhooks	목록
GET	/workspaces/me/webhooks/{webhookId}	단건 조회
PATCH	/workspaces/me/webhooks/{webhookId}	수정
DELETE	/workspaces/me/webhooks/{webhookId}	삭제
POST	/workspaces/me/webhooks/{webhookId}/regenerate-secret	시크릿 회전
POST	/workspaces/me/webhooks/{webhookId}/toggle	상태 전환
GET	/workspaces/me/webhooks/{webhookId}/delivery-logs	전달 로그