# 받아쓰기 웹훅으로 완료와 실패 알림 받기

> 받아쓰기 웹훅을 쓰려면 요청에 webhook_url을 넣으세요. 변환이 완료되거나 실패하면 서명된 POST를 보내요. 상태를 반복 조회하지 않고 알림을 받을 수 있어요.

Canonical: https://transcript1.com/ko/features/badasseugi-wephuk
Language: ko
Last updated: 2026-10-19

받아쓰기 웹훅을 설정하면 상태를 계속 조회하지 않아도 돼요. 변환을 만들 때 webhook_url을 넣으세요. 완료되거나 실패하면 지정한 URL로 서명된 POST를 보내요.

- transcription.completed와 transcription.failed 알림
- 모든 전송에 HMAC-SHA256 서명
- 간격을 늘려 가며 최대 6회 전송 시도

## 알림을 받은 뒤 필요한 스크립트만 조회하세요

### 완료와 실패만 알림

이벤트는 transcription.completed와 transcription.failed예요. 취소한 변환에는 웹훅을 보내지 않아요.

### 팀의 시크릿으로 서명 확인

X-Transcript1-Signature 헤더에 타임스탬프와 HMAC-SHA256 서명이 담겨요. 팀의 whsec_ 시크릿으로 원본 본문을 검증하세요.

### 받지 못하면 다시 전송

2xx 응답이면 전달한 것으로 처리해요. 그 외에는 2, 4, 8, 16, 32분 뒤 재시도해요. 첫 전송을 포함해 최대 6회예요.

### 공개 HTTPS 주소만 사용

URL은 공개 주소로 연결되는 HTTPS여야 해요. 변환을 만들 때와 전송할 때마다 확인해요.

### 본문은 작게, 스크립트는 별도 조회

이벤트에는 변환 객체만 담고 스크립트는 넣지 않아요. 받은 ID로 원하는 형식의 스크립트를 조회하세요.

## 변환 요청에 webhook\_url 넣기

영상 링크 요청, 청크 업로드 예약, 파일을 한 번에 보내는 폼에 webhook_url을 넣을 수 있어요. reuse_recent와는 함께 쓸 수 없어요. [웹훅 설정 문서](https://transcript1.com/ko/docs/webhooks#set-a-webhook-url)를 확인하세요.

인터뷰 파일이나 여러 영상처럼 요청이 끝난 뒤에도 처리가 이어지는 작업에 잘 맞아요. 변환 ID를 앱의 작업 기록과 함께 저장해 두면 알림이 왔을 때 어느 사용자의 요청인지 찾을 수 있어요.

리디렉션하는 주소 말고 최종 공개 HTTPS 엔드포인트를 지정하세요. 생성 시점과 전송 시점에 주소를 검사해요. 개발 중에도 localhost는 수신 주소로 쓸 수 없어요. 아래 예제처럼 직접 가진 녹음으로 알림 흐름을 테스트하세요.

### 완료 웹훅을 설정한 파일 업로드

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## 중복 알림을 처리한 뒤 스크립트 가져오기

data에는 스크립트를 제외한 변환 객체가 들어 있어요. data.id와 type을 묶어 중복을 구분하세요. 완료 이벤트라면 [조회 API](https://transcript1.com/ko/docs/api-reference#get-a-transcription)로 스크립트를 가져오세요.

같은 이벤트가 여러 번 올 수 있다고 가정하세요. 수신 처리를 끝냈어도 응답이 10초보다 늦으면 다시 보낼 수 있어요. 알림이나 게시 작업 전에 변환 ID와 이벤트 종류를 중복 확인용 키로 저장하세요.

서명을 확인한 뒤 이벤트를 저장소나 큐에 확실히 남기고 빠르게 2xx로 응답하세요. 스크립트는 백그라운드 작업에서 data.id로 가져오면 돼요. transcription.failed면 data.error를 확인해 앱의 상태를 갱신하세요. 취소에는 알림이 없으니 취소 처리에서 상태를 직접 바꾸세요.

### 수신 URL로 보내는 POST 예시

```
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을 계산하세요. 서명은 상수 시간 비교 함수로 확인하고 너무 오래된 타임스탬프는 거부하세요. [전체 검증 절차](https://transcript1.com/ko/docs/webhooks#verify-the-signature)를 참고하세요.

JSON 파서가 읽기 전의 원본 본문이 필요해요. 파싱한 JSON을 다시 문자열로 만들면 공백이나 키 순서가 바뀔 수 있어요. 헤더와 타임스탬프를 확인하고, 길이가 같은 서명을 상수 시간으로 비교한 뒤 본문을 파싱하세요.

아래 코드는 t와 v1을 이미 추출하고 검사했다고 가정한 짧은 예시예요. 문서에는 5분의 시간 오차를 허용하는 Node.js와 Python 전체 예제가 있어요. whsec_ 접두사까지 포함한 시크릿 전체를 쓰세요. 팀 시크릿을 교체하면 이후 전송부터 바로 새 키를 사용해요.

### Node.js

```
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));
```

- [서명 검증 전체 예제](https://transcript1.com/ko/docs/webhooks)

## 정상 수신뿐 아니라 실패와 중복도 테스트하세요

완료, 실패, 중복 이벤트를 각각 보내 보세요. 같은 완료 알림으로 두 번 게시하지 않는지, 실패한 작업을 스크립트가 있는 것처럼 처리하지 않는지 확인하세요. 서명 거부와 앱 처리 오류는 따로 테스트하세요.

전송 타임아웃은 10초예요. 색인이나 모델 호출이 끝날 때까지 응답을 미루지 마세요. 이벤트를 저장하고 응답한 뒤 후속 작업은 앱의 큐에서 재시도하세요. 웹훅 재전송이 앱의 후속 작업 재시도까지 대신하지는 않아요.

2xx가 아닌 응답, 연결 오류, 타임아웃이면 2, 4, 8, 16, 32분 간격으로 재시도해요. 총 6회까지 시도하며 리디렉션은 따라가지 않아요. 변환 ID, 이벤트 종류, 전송 상태를 로그에 남기고 서명 시크릿은 남기지 마세요.

재시도가 모두 끝나면 저장해 둔 ID로 [변환 상태를 조회](https://transcript1.com/ko/docs/api-reference#get-a-transcription)해 맞춰 보세요. 콜백이 유일한 작업 기록이어서는 안 돼요. 생성할 때 ID를 남겨야 알림이 없어도 같은 파일을 다시 보내지 않고 원인을 찾을 수 있어요.

## 자주 묻는 질문

### 서명 시크릿은 어디서 확인하나요?

대시보드의 “Webhooks”에서 확인하세요. whsec_로 시작하는 팀 공용 시크릿이에요. 같은 화면에서 언제든 교체할 수 있어요.

### 알림 전송에 실패하면 어떻게 되나요?

간격을 늘려 가며 약 1시간 동안 최대 6회 시도해요. 전송마다 타임아웃은 10초예요. 리디렉션은 따라가지 않아요.

### MCP에서도 웹훅을 설정할 수 있나요?

아니요. 웹훅은 REST API에서만 쓸 수 있어요. MCP 도구는 잠시 기다리거나 ID를 돌려주고, 그 ID로 나중에 조회해요.

## 함께 보면 좋은 페이지

- [웹훅 연동 (문서)](https://transcript1.com/ko/docs/webhooks)
- [파일 변환 API](https://transcript1.com/ko/features/eumseong-tekseuteu-byeonhwan-api)
- [AI 에이전트 연동](https://transcript1.com/ko/use-cases/ai-eijeonteu-yeongsang-seukeuripteu)