웹훅: HMAC 서명, 재전송 및 모범 사례

아니요. 보안상 https URL만 허용하며, 리디렉션이 없어야 하고 내부/사설 주소는 차단됩니다.

이벤트 유형을 식별하는 X-VPT-Event 헤더와 전달 본문의 내용으로 구분합니다.

웹훅으로 전사 결과를 수신하는 방법: HMAC-SHA256 서명, X-VPT-Signature 및 X-VPT-Event 헤더, 백오프가 적용된 재전송 6회 시도.

전사가 끝났는지 API를 계속 폴링하는 대신, 요청에 webhook_url을 지정하면 VoxScriber가 작업이 완료될 때(성공 또는 실패) 서버로 POST를 보냅니다. 이는 권장되는 통합 방식입니다: 요청 수를 줄이고 결과를 즉시 받을 수 있습니다.

작동 방식

각 전달에는 두 개의 식별 헤더가 포함됩니다:

헤더	내용
`X-VPT-Event`	이벤트 유형(완료, 실패 등)
`X-VPT-Signature`	전달에 대한 HMAC-SHA256 서명

콘텐츠를 신뢰하기 전에 항상 서명을 검증하세요: 수신한 본문의 HMAC-SHA256을 계산하여 X-VPT-Signature 헤더 값과 비교하세요. 유효한 서명이 없는 요청은 폐기해야 합니다 — 누구나 엔드포인트의 URL을 알 수 있습니다.

엔드포인트가 다운되거나 응답이 너무 느리면 다시 시도합니다:

모든 전달은 저희 쪽에 저장되므로, 문제가 발생하면 지원팀과 함께 기록을 감사할 수 있습니다.

웹훅에 즉시 200으로 응답하고 콘텐츠를 비동기적으로(큐, 잡) 처리하세요. 처리 시간이 15초를 초과하면 전달이 실패로 간주되어 재전송 대기열에 들어갑니다 — 결국 동일한 이벤트를 두 번 받을 수 있습니다. 이벤트를 멱등적으로 처리하세요.

멈춘 작업은 조용히 사라지지 않습니다:

즉, 전송된 각 오디오에 대해 시스템은 성공 또는 실패의 최종 콜백을 받게 됩니다.

서버가 다운되었습니다. 결과를 잃었나요?

아마 아닙니다: 약 24시간에 걸쳐 최대 6회 시도합니다. 모두 실패하면 전달 기록이 남습니다 — 재처리를 위해 지원팀에 문의하세요.

http URL(TLS 없음)을 사용할 수 있나요?

아니요. 보안상 https URL만 허용하며, 리디렉션이 없어야 하고 내부/사설 주소는 차단됩니다.

성공 웹훅과 오류 웹훅을 어떻게 구분하나요?

이벤트 유형을 식별하는 X-VPT-Event 헤더와 전달 본문의 내용으로 구분합니다.

내 엔드포인트는 무엇으로 응답해야 하나요?

15초 이내의 모든 2xx 상태입니다. 다른 상태(또는 타임아웃)는 실패로 간주되어 재전송됩니다.