Skip to main content
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.
FieldTypeDescription
urlstringDestination URL that receives webhook events
enabledbooleanWhether webhook delivery is enabled
eventsarrayList of subscribed events
secretstringSigning secret used for signature verification
updatedAtstringISO timestamp of last update

​
Supported events

Travelbase emits webhook events for important lifecycle changes.
EventDescription
order.createdOrder successfully created
order.ticketedOrder successfully ticketed
order.failedOrder failed during processing
refund.createdRefund created for an order
wallet.updatedWallet 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

FieldTypeRequiredDescription
urlstringYesHTTPS endpoint that receives events
enabledbooleanYesEnable or disable webhook delivery
eventsarrayYesEvents to subscribe to
rotateSecretbooleanNoGenerate 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.
HeaderDescription
x-webhook-idUnique identifier for the webhook delivery
x-webhook-eventEvent type (for example, order.ticketed)
x-webhook-timestampISO timestamp indicating when the event was generated
x-webhook-signatureHMAC 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:
ComponentDescription
secretYour webhook signing secret
timestampValue from the x-webhook-timestamp header
payloadRaw 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.
```