Skip to content

Webhook Events

In addition to polling the API for events, Thailand Boat Tickets (TBT) can push events directly to your system via Webhooks. This allows for real-time integration without the need for constant polling.

How it Works

  1. Configuration: You provide TBT support with a Webhook URL (API endpoint) on your server or automation platform (like Zapier, n8n, Make, etc.).
  2. Trigger: When a booking event occurs (e.g., a new booking is paid), our system creates an event record.
  3. Delivery: Our system immediately attempts to POST the event data to your configured Webhook URL.
  4. Status Updates:
    • If your server responds with a success status code (200-299), the event is marked as DELIVERED.
    • If the request fails (timeout, 500 error, etc.), our system will retry.

Retry Policy

To ensure reliable delivery, we implement an exponential backoff retry mechanism:

  • Max Retries: 3 attempts.
  • Backoff: The system waits increasingly longer between retries (exponentially).
  • Failure: If all retries fail, the event status is marked as FAILED. You can still retrieve these failed events via the API.

Payload Structure

When TBT sends a webhook to your URL, the HTTP POST body will contain a JSON object with the following structure:

{
  "event_name": "bookings.create",
  "payload": {
    "booking": {
      "contact_first_name": "Jane",
      "contact_last_name": "Doe",
      "status": "CONFIRMED",
      "price": 1500,
      "code": "BOOK_123",
      "route_name": "Phuket -> Phi Phi",
      "date_departure": "2023-12-25T09:00:00",
      ...
    }
  }
}

Note: The structure inside payload is identical to what you receive when querying the /operator-api/v1/events endpoint.

Security

If you need to verify that the request originated from TBT, please contact support to establish a shared secret or IP allowlisting strategy suitable for your infrastructure.