변환 요청에 webhook_url 넣기
영상 링크 요청, 청크 업로드 예약, 파일을 한 번에 보내는 폼에 webhook_url을 넣을 수 있어요. reuse_recent와는 함께 쓸 수 없어요. 웹훅 설정 문서를 확인하세요.
인터뷰 파일이나 여러 영상처럼 요청이 끝난 뒤에도 처리가 이어지는 작업에 잘 맞아요. 변환 ID를 앱의 작업 기록과 함께 저장해 두면 알림이 왔을 때 어느 사용자의 요청인지 찾을 수 있어요.
리디렉션하는 주소 말고 최종 공개 HTTPS 엔드포인트를 지정하세요. 생성 시점과 전송 시점에 주소를 검사해요. 개발 중에도 localhost는 수신 주소로 쓸 수 없어요. 아래 예제처럼 직접 가진 녹음으로 알림 흐름을 테스트하세요.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1중복 알림을 처리한 뒤 스크립트 가져오기
data에는 스크립트를 제외한 변환 객체가 들어 있어요. data.id와 type을 묶어 중복을 구분하세요. 완료 이벤트라면 조회 API로 스크립트를 가져오세요.
같은 이벤트가 여러 번 올 수 있다고 가정하세요. 수신 처리를 끝냈어도 응답이 10초보다 늦으면 다시 보낼 수 있어요. 알림이나 게시 작업 전에 변환 ID와 이벤트 종류를 중복 확인용 키로 저장하세요.
서명을 확인한 뒤 이벤트를 저장소나 큐에 확실히 남기고 빠르게 2xx로 응답하세요. 스크립트는 백그라운드 작업에서 data.id로 가져오면 돼요. transcription.failed면 data.error를 확인해 앱의 상태를 갱신하세요. 취소에는 알림이 없으니 취소 처리에서 상태를 직접 바꾸세요.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}HMAC으로 웹훅 서명 검증하기
whsec_ 시크릿을 키로 써서 t, 마침표, 원본 본문을 이어 붙인 문자열의 HMAC-SHA256을 계산하세요. 서명은 상수 시간 비교 함수로 확인하고 너무 오래된 타임스탬프는 거부하세요. 전체 검증 절차를 참고하세요.
JSON 파서가 읽기 전의 원본 본문이 필요해요. 파싱한 JSON을 다시 문자열로 만들면 공백이나 키 순서가 바뀔 수 있어요. 헤더와 타임스탬프를 확인하고, 길이가 같은 서명을 상수 시간으로 비교한 뒤 본문을 파싱하세요.
아래 코드는 t와 v1을 이미 추출하고 검사했다고 가정한 짧은 예시예요. 문서에는 5분의 시간 오차를 허용하는 Node.js와 Python 전체 예제가 있어요. whsec_ 접두사까지 포함한 시크릿 전체를 쓰세요. 팀 시크릿을 교체하면 이후 전송부터 바로 새 키를 사용해요.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));정상 수신뿐 아니라 실패와 중복도 테스트하세요
완료, 실패, 중복 이벤트를 각각 보내 보세요. 같은 완료 알림으로 두 번 게시하지 않는지, 실패한 작업을 스크립트가 있는 것처럼 처리하지 않는지 확인하세요. 서명 거부와 앱 처리 오류는 따로 테스트하세요.
전송 타임아웃은 10초예요. 색인이나 모델 호출이 끝날 때까지 응답을 미루지 마세요. 이벤트를 저장하고 응답한 뒤 후속 작업은 앱의 큐에서 재시도하세요. 웹훅 재전송이 앱의 후속 작업 재시도까지 대신하지는 않아요.
2xx가 아닌 응답, 연결 오류, 타임아웃이면 2, 4, 8, 16, 32분 간격으로 재시도해요. 총 6회까지 시도하며 리디렉션은 따라가지 않아요. 변환 ID, 이벤트 종류, 전송 상태를 로그에 남기고 서명 시크릿은 남기지 마세요.
재시도가 모두 끝나면 저장해 둔 ID로 변환 상태를 조회해 맞춰 보세요. 콜백이 유일한 작업 기록이어서는 안 돼요. 생성할 때 ID를 남겨야 알림이 없어도 같은 파일을 다시 보내지 않고 원인을 찾을 수 있어요.