웹훅
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
Job이 종료 상태(terminal)에 도달했을 때 서버가 알림을 받아야 한다면 웹훅을 사용하세요.
이 페이지는 생성 Job에 대한 문서입니다. Sume에는 웹훅 표면이 두 가지 있습니다.
| You called | You get | Documented at |
|---|---|---|
POST /v1/models/... 또는 /v1/avatar-1.0/generate 같은 모델 엔드포인트 | job.completed / job.failed / job.canceled | 이 페이지 |
| Action, Format, Agent Completion run 엔드포인트 | action.run.terminal / format.run.terminal / agent.run.terminal | Run 웹훅 |
이벤트 집합은 겹치지 않고 payload도 다릅니다. run 웹훅은 Job 결과가 아니라 전체 run receipt를 담습니다. 서명 방식은 동일하므로 검증기 하나로 둘 다 처리할 수 있습니다.
웹훅 URL과 함께 제출하기
mode: "webhook"와 webhook_url을 보내세요.
웹훅 URL은 공개 HTTPS URL이어야 합니다. Localhost, private-network, non-HTTPS URL은 거절됩니다.
웹훅은 네 가지 통신 모드 중 하나입니다. async, sync, subscribe와 어떻게 다른지, 그리고 웹훅과 함께 유지해야 할 폴링 폴백은 통신 모드에서 살펴보세요.
이벤트
Sume는 종료 Job 이벤트만 보냅니다. 진행 상황이나 부분 전달은 없습니다.
| Event | When it is sent |
|---|---|
job.completed | Job이 완료되어 공개 결과를 사용할 수 있을 때입니다. |
job.failed | Job이 공개 오류와 함께 실패했을 때입니다. |
job.canceled | Job이 canceled 상태에 도달했을 때입니다. |
Payload
실패·취소 웹훅은 status: "ERROR"를 쓰고 error 객체를 포함합니다.
서명 헤더
웹훅 서명이 설정돼 있으면 Sume는 원본 JSON body를 아래 문자열에 대해 HMAC SHA-256으로 서명합니다.
헤더:
타임스탬프가 재생 허용 창을 벗어나면 콜백을 거절하세요. 5분이 합리적 기본값입니다.
서명 시크릿은 대시보드의 웹훅 탭(/dashboard/webhooks — 표시 후 복사)에서 직접 확인하거나, account:read 범위를 가진 API 키로 GET /v1/webhooks/signing-secret을 호출해 받을 수 있습니다. 워크스페이스별로 파생된 값이므로 플랫폼 공용 값이 아니라 여러분 전용입니다. 전달 워커가 서명할 때 쓰는 것과 같은 이름인 SUME_COM_WEBHOOK_SIGNING_SECRET으로 저장하세요. Job 웹훅과 Run 웹훅은 이 시크릿 하나를 공유하므로 검증기 하나로 둘 다 처리할 수 있습니다.
모든 전송에는 x-sume-webhook-secret-fingerprint 헤더가 실리고, 영수증의 webhook_delivery.signing_secret_fingerprint에도 같은 값이 담깁니다. 서명 검증이 실패하면 대시보드에서 시크릿 옆에 표시된 지문과 비교하세요. 시크릿 자체를 주고받을 필요가 없습니다.
TypeScript에서 검증하기
전달 동작
이벤트를 내구성 있게 저장한 뒤 2xx를 반환하세요. 네트워크 오류와 non-2xx는 시도가 소진될 때까지 재시도됩니다. 서버 쪽 idempotency 키로는 job_id를 사용하세요.
| 재시도 | 최대 10회입니다. |
| 간격 | 지수 백오프가 아니라 시도 사이의 고정 지연(기본 30초)입니다. |
| 타임아웃 | 시도당 10초입니다. 느린 엔드포인트는 이 예산을 소진하고 재시도를 부릅니다. |
10회가 모두 거부되면 남는 것은 실패한 전달이며, Job 자체는 실제 종료 상태에 그대로 도달해 있습니다. 전달은 최적화이지 유일한 복구 경로가 아닙니다. 도착하지 않은 이벤트를 위해 status_url 폴링을 쓸 수 있게 유지하세요. 전달 카운터는 Job 객체와 Job 이벤트에서 확인할 수 있습니다.
Run 웹훅도 같은 10회 상한을 쓰지만 일정이 다릅니다. *.run.terminal 전달은 그 페이지가 기준입니다.
다음
- Run 웹훅 — Action, Format, Agent Completion run에 같은 서명 방식