웹훅 이벤트

티켓타코 웹훅의 전송 방식과 이벤트 목록입니다. 웹훅 등록 방법과 재전송 정책은 웹훅 연결하기 가이드를 참고해주세요.

시작하기

전송 방식

이벤트가 발생하면 등록한 웹훅 URL로 HTTPS POST 요청을 보냅니다. 요청 본문은 JSON이며, 아래 헤더가 함께 전송됩니다.

Content-Type: application/json
ticketaco-webhook-delivery-id: 550e8400-e29b-41d4-a716-446655440000
ticketaco-webhook-delivery-retry-count: 0

ticketaco-webhook-delivery-id
웹훅 전송 건의 고유 식별자입니다. 재전송 시에도 동일한 값이 유지되어, 중복 처리를 막는 데 사용할 수 있습니다.


ticketaco-webhook-delivery-retry-count
웹훅이 재전송된 횟수입니다. 처음 전송할 때는 0입니다. 재전송 정책을 참고해주세요.

이벤트 본문

모든 웹훅 이벤트는 아래 형식으로 전송됩니다. 일부 이벤트에는 status, reason 필드가 추가로 포함됩니다.

{
  "type": "order.completed",
  "test": true,
  "created_at": "2025-04-07T14:30:00.000Z",
  "data": {
    // ...
  }
}

type string
웹훅 이벤트 타입입니다.


test optional boolean
테스트 전송 여부입니다. 라이브 웹훅에는 포함되지 않습니다.


created_at string
웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSZ ISO 8601 형식이며, UTC 기준입니다.


data object
이벤트가 발생한 객체입니다. 웹훅이 생성된 시점의 최신 정보입니다.


이벤트

order.completed

주문이 완료되면 주문 단위로 전송됩니다. 한 번에 3장을 예매해도 이벤트는 1건입니다. 추첨·승인 티켓은 선정 후 결제까지 완료되면 전송됩니다.

이벤트 본문

data는 Order 객체입니다.

{
  "type": "order.completed",
  "test": true,
  "created_at": "2025-04-07T14:30:00.000Z",
  "data": {
    "order_number": "P0000000001",
    "event_id": "a1b2c3d4",
    "name": "FEConf 2025",
    "quantity": 2,
    "total_amount": 40000,
    "refund_amount": 0,
    "status": "paid"
    // ...
  }
}

ticket.status_changed

티켓 상태가 변경되면 티켓 단위로 전송됩니다. 예를 들어 한 번에 예매한 3장 중 1장을 취소하면 이벤트는 1건, 3장 모두 취소하면 3건입니다.

이벤트 본문

data는 Ticket 객체입니다. 이벤트 본문에 status 필드가 추가로 포함됩니다.

{
  "type": "ticket.status_changed",
  "test": true,
  "created_at": "2025-04-07T14:25:00.000Z",
  "status": "used",
  "data": {
    "ticket_number": "T0000000001",
    "order_number": "P0000000001",
    "ticket_type_name": "일반 참가권",
    "status": "used"
    // ...
  }
}

status string
변경된 티켓 상태입니다.

  • used: 체크인하여 티켓이 사용된 상태로 변경된 경우입니다.
  • paid: 체크인이 취소되어 결제 완료 상태로 되돌아간 경우입니다.
  • canceled: 티켓이 취소된 경우입니다.

ticket.updated

티켓 정보가 변경되면 전송됩니다. 체크인이나 취소 같은 상태 변화는 ticket.status_changed 이벤트로 전송됩니다.

이벤트 본문

data는 Ticket 객체입니다. 이벤트 본문에 reason 필드가 추가로 포함됩니다.

{
  "type": "ticket.updated",
  "test": true,
  "created_at": "2025-04-08T15:00:00.000Z",
  "reason": "transferred",
  "data": {
    "ticket_number": "T0000000001",
    "order_number": "P0000000001",
    "ticket_type_name": "일반 참가권",
    "status": "paid"
    // ...
  }
}

reason string
티켓이 변경된 사유입니다.

  • attendee_updated: 참가자 정보(이름, 연락처 등)가 변경된 경우입니다.
  • answers_updated: 참가 양식 답변이 변경된 경우입니다.
  • transferred: 양도가 완료되어 소유자가 변경된 경우입니다.
  • deposit_refunded: 참가 보증금이 환불된 경우입니다.

entry.created

추첨·승인 방식의 티켓에서 참가신청이 완료되면 전송됩니다.

이벤트 본문

data는 Entry 객체입니다.

{
  "type": "entry.created",
  "test": true,
  "created_at": "2025-04-05T09:00:00.000Z",
  "data": {
    "entry_number": "E0000000001",
    "event_id": "a1b2c3d4",
    "name": "FEConf 2025",
    "ticket_type_name": "추첨 참가권",
    "status": "pending"
    // ...
  }
}

entry.status_changed

추첨·승인 방식의 티켓에서 참가신청 상태가 변경되면 전송됩니다. 선정된 참가신청은 등록된 카드로 자동 결제되면 바로 paid로, 직접 결제해야 하거나 자동 결제에 실패하면 awaiting_payment로 전송됩니다.

이벤트 본문

data는 Entry 객체입니다. 이벤트 본문에 status 필드가 추가로 포함됩니다.

{
  "type": "entry.status_changed",
  "test": true,
  "created_at": "2025-04-06T11:00:00.000Z",
  "status": "awaiting_payment",
  "data": {
    "entry_number": "E0000000001",
    "event_id": "a1b2c3d4",
    "name": "FEConf 2025",
    "ticket_type_name": "추첨 참가권",
    "status": "awaiting_payment"
    // ...
  }
}

status string
변경된 참가신청 상태입니다.

  • awaiting_payment: 추첨에 당첨되거나 승인되어 결제를 기다리는 경우입니다.
  • paid: 결제가 완료된 경우입니다. 자동 결제로 선정과 동시에 결제된 경우도 포함됩니다.
  • payment_expired: 결제 기한이 초과되어 만료된 경우입니다.
  • rejected: 추첨에 미당첨되거나 미승인된 경우입니다.
  • canceled: 신청이 취소된 경우입니다.

entry.updated

추첨·승인 방식의 티켓에서 참가신청 정보가 변경되면 전송됩니다. 결제 대기나 취소 같은 상태 변화는 entry.status_changed 이벤트로 전송됩니다.

이벤트 본문

data는 Entry 객체입니다. 이벤트 본문에 reason 필드가 추가로 포함됩니다.

{
  "type": "entry.updated",
  "test": true,
  "created_at": "2025-04-06T12:00:00.000Z",
  "reason": "attendees_updated",
  "data": {
    "entry_number": "E0000000001",
    "event_id": "a1b2c3d4",
    "name": "FEConf 2025",
    "ticket_type_name": "추첨 참가권",
    "status": "pending"
    // ...
  }
}

reason string
참가신청이 변경된 사유입니다.

  • attendees_updated: 참가자 정보(이름, 연락처 등)가 변경된 경우입니다.
  • answers_updated: 참가 양식 답변이 변경된 경우입니다.