웹훅(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회 이상 실패하면 이메일로 알려드립니다.