Webhooks allow Travelbase to notify your system in real time when important events occur, such as orders being ticketed, refunds being created, or wallet balances changing. Instead of polling the API, your system receives secure HTTP POST requests whenever subscribed events occur.

Real-time notifications

Receive events instantly when resources change.

Secure delivery

Every webhook delivery includes an HMAC signature for verification.

Webhook configuration object

The webhook configuration defines where events are delivered and which events are enabled.

Field	Type	Description
url	string	Destination URL that receives webhook events
enabled	boolean	Whether webhook delivery is enabled
events	array	List of subscribed events
secret	string	Signing secret used for signature verification
updatedAt	string	ISO timestamp of last update

Supported events

Travelbase emits webhook events for important lifecycle changes.

Event	Description
order.created	Order successfully created
order.ticketed	Order successfully ticketed
order.failed	Order failed during processing
refund.created	Refund created for an order
wallet.updated	Wallet balance or transaction changed

Subscribe only to events your system requires to reduce unnecessary webhook traffic.

Get webhook configuration

Retrieve your current webhook configuration.

GET /v1/webhooks

Response

{
"success": "true",
"data":{
   "webhook": {
   "url": "https://example.com/webhooks",
   "enabled": true,
   "events": [
   "order.created",
   "order.ticketed"
   ],
   "secret": "base64-...",
   "updatedAt": "2026-02-20T16:25:51.293Z"
   }
}}

Create or update webhook configuration

Create or update your webhook endpoint and event subscriptions.

PUT /v1/webhooks

Request body

{
"url": "https://example.com/webhooks",
"enabled": true,
"events": [
"order.created",
"order.ticketed",
"order.failed",
"refund.created",
"wallet.updated"
],
"rotateSecret": false
}

Fields

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint that receives events
enabled	boolean	Yes	Enable or disable webhook delivery
events	array	Yes	Events to subscribe to
rotateSecret	boolean	No	Generate a new signing secret

Response

{
  "success": "true",
  "data": {
    "webhook": {
      "url": "https://example.com/webhooks",
      "enabled": true,
      "events": [
        "order.created",
        "order.ticketed"
      ],
      "secret": "base64-...",
      "updatedAt": "2026-02-20T16:25:51.293Z"
  }}
}

If you rotate your webhook secret, you must immediately update your verification logic.

Webhook delivery format

Travelbase delivers webhook events as HTTP POST requests with a JSON payload. Example delivery

{
"id": "evt_01hzy9k2yz",
"type": "order.ticketed",
"created_at": "2026-02-20T16:25:51.293Z",
"data": {
"order_id": "ord_123",
"status": "ticketed"
}
}

Delivery headers

Each webhook delivery includes security and metadata headers to help your system verify authenticity and process events safely.

Header	Description
`x-webhook-id`	Unique identifier for the webhook delivery
`x-webhook-event`	Event type (for example, `order.ticketed`)
`x-webhook-timestamp`	ISO timestamp indicating when the event was generated
`x-webhook-signature`	HMAC SHA-256 signature used to verify authenticity

Always verify webhook signatures before processing events to prevent unauthorized requests.

Signature verification

Travelbase signs each webhook delivery using your webhook secret. Your system must verify this signature before accepting the event.

Signature format

The signature is generated using HMAC SHA-256:

HMAC_SHA256(secret, `${timestamp}.${payload}`)

Signature components

The signature is generated using the following components:

Component	Description
`secret`	Your webhook signing secret
`timestamp`	Value from the `x-webhook-timestamp` header
`payload`	Raw HTTP request body exactly as received

Verification example (Node.js)

Use the following example to verify webhook signatures securely:

import crypto from "crypto";

export function verifyWebhookSignature({
  secret,
  payload,
  timestamp,
  signature
}) {
  const signedPayload = `${timestamp}.${payload}`;

  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  );
}

Always use the raw request body exactly as received. Any modification to the payload will invalidate the signature.

Delivery guarantees

Travelbase provides reliable and fault-tolerant webhook delivery to ensure your system receives critical events.

Automatic retries

Failed webhook deliveries are retried automatically using exponential backoff until successful.

At-least-once delivery

Webhooks are guaranteed to be delivered at least once. Your system must safely handle duplicate deliveries.

Best practices Follow these best practices to ensure secure, reliable, and production-ready webhook handling.

Verify signatures

Always verify the webhook signature before processing events.

Respond quickly

Return an HTTP 200 response immediately after receiving the webhook to prevent retries.

Implement idempotency

Store and track webhook event IDs to prevent duplicate processing.

Use secure endpoints

Only configure HTTPS endpoints to ensure secure communication.

```

Location

Search

Orders

Financial

Platform

Webhooks

Real-time notifications

Secure delivery

Webhook configuration object

Supported events

Get webhook configuration

Response

Create or update webhook configuration

Request body

Fields

Response

Webhook delivery format

Delivery headers

Signature verification

Signature format

Signature components

Verification example (Node.js)

Delivery guarantees

Automatic retries

At-least-once delivery

Verify signatures

Respond quickly

Implement idempotency

Use secure endpoints

Real-time notifications

Secure delivery

​Webhook configuration object

​Supported events

​Get webhook configuration

​Response

​Create or update webhook configuration

​Request body

​Fields

​Response

​Webhook delivery format

​Delivery headers

​Signature verification

​Signature format

​Signature components

​Verification example (Node.js)

​Delivery guarantees

Automatic retries

At-least-once delivery

Verify signatures

Respond quickly

Implement idempotency

Use secure endpoints

Webhook configuration object

Supported events

Get webhook configuration

Response

Create or update webhook configuration

Request body

Fields

Response

Webhook delivery format

Delivery headers

Signature verification

Signature format

Signature components

Verification example (Node.js)

Delivery guarantees