웹훅(Webhook) 연결하기
참가자의 티켓, 참가신청에 변경사항이 있을 때 웹훅으로 실시간 업데이트를 받아보세요. 웹훅이란 데이터가 변경되었을 때 실시간으로 알림을 받을 수 있는 기능이에요. 예를 들어, 참가자가 티켓을 결제하면 Slack 채널에 알림을 보내거나 Google Sheets에 데이터를 기록하는 등 다양하게 활용할 수 있어요.
참가자 결제 완료 → Ticketaco → POST https://your-server.com/webhook → Slack 알림
전송 방식, 이벤트 본문 등 사용 정보는 웹훅 이벤트를 참고해주세요.
이벤트 타입
웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다. 웹훅 본문과 자세한 설명은 각 이벤트 타입을 선택해서 살펴보세요.
| 이벤트 타입 | 설명 |
|---|---|
order.completed |
주문 완료 이벤트입니다. |
ticket.status_changed |
티켓 상태 변경(체크인, 체크인 취소, 취소) 이벤트입니다. |
ticket.updated |
티켓 정보 변경(참가자 정보, 참가 양식 답변, 양도, 보증금 환불) 이벤트입니다. |
entry.created |
추첨·승인 티켓 참가신청 완료 이벤트입니다. |
entry.status_changed |
추첨·승인 티켓 참가신청 상태 변경(결제 대기, 결제 완료, 결제 만료, 미선정, 취소) 이벤트입니다. |
entry.updated |
추첨·승인 티켓 참가신청 정보 변경(참가자 정보, 참가 양식 답변) 이벤트입니다. |
웹훅 등록
개발자센터의 웹훅 메뉴에서 등록 버튼을 누르면 웹훅 이벤트 등록 팝업창이 열립니다. 웹훅 이름, 웹훅 URL을 입력하고 등록할 이벤트를 선택하세요. 마지막으로 ’저장’을 누르면 웹훅이 등록됩니다.
웹훅 목록에서 잘 등록되었는지 확인하세요. 등록한 이벤트가 발생하면 웹훅 URL로 웹훅 이벤트가 전송됩니다. 웹훅은 상세 페이지에서 삭제할 수 있습니다.

- 웹훅 URL은
https://로 시작해야 합니다. - 웹훅 URL은 외부에서 접근할 수 있는 주소여야 합니다.
localhost같은 로컬 개발 환경 주소로는 웹훅을 받을 수 없습니다. - 조직당 최대 10개의 웹훅을 등록할 수 있습니다.
웹훅 받기
이벤트가 발생하면 등록한 URL로 JSON 본문이 담긴 POST 요청이 전송됩니다. 서버에서 웹훅을 받을 때 아래 내용을 확인해주세요.
- 10초 이내에 200번대 상태 코드로 응답해주세요. 응답하지 않거나 실패 응답을 보내면 웹훅이 재전송됩니다.
ticketaco-webhook-delivery-id헤더로 재전송된 웹훅을 이미 처리했는지 확인할 수 있습니다.- 테스트 전송 버튼으로 웹훅을 테스트할 수 있습니다. 테스트 웹훅에는
"test": true가 포함됩니다.
app.post("/webhook", express.json(), async (req, res) => {
const deliveryId = req.get("ticketaco-webhook-delivery-id");
try {
// 웹훅을 처리하거나 나중에 처리할 수 있도록 저장한 뒤 응답합니다
await handleWebhook(deliveryId, req.body);
res.sendStatus(200);
} catch {
// 실패하면 실패로 응답해 웹훅을 다시 받습니다
res.sendStatus(500);
}
});
전송 기록과 재전송
개발자센터 웹훅 목록에서 등록한 웹훅을 선택하면 웹훅 상세 정보와 전송 기록을 확인할 수 있습니다.

전송 기록에는 발생한 이벤트마다 한 줄씩 표시됩니다. 웹훅이 재전송되어도 줄이 새로 생기지 않고, 같은 줄의 상태가 최신 결과로 바뀝니다. 이벤트 발생 시간을 누르면 전송된 본문을 볼 수 있습니다. 전송 기록은 30일 동안 보관된 뒤 자동으로 삭제됩니다.
전송 상태는 ‘전송 중’, ‘성공’, ‘실패’ 중 하나입니다. 10초 안에 응답하지 않거나 200번대가 아닌 상태 코드로 응답하면 전송 실패로 처리하고, 아래 간격으로 최대 5회까지 재전송합니다.
| 재전송 횟수 | 재전송 간격(분) |
|---|---|
| 1 | 1 |
| 2 | 4 |
| 3 | 16 |
| 4 | 64 |
| 5 | 256 |
- 재전송하는 동안에는 ’전송 중’으로 표시되고, 5회 재전송까지 실패하면 ’실패’로 바뀝니다.
- 웹훅 한 건의 전송이 3회 이상 실패하면 이메일로 알려드립니다.