RollingGo Webhooks — Register, Verify, and Handle Events

Webhooks let you receive real-time HTTP notifications whenever a booking’s status changes — for example, when a reservation moves from pending to confirmed, or when a carrier cancels a booking on your behalf. Instead of polling GET /travel/booking/{id}, you register a URL and RollingGo pushes event payloads to it automatically. This feature is available to Enterprise and Developer partners.

Base URLs

International: https://api.rollinggo.ai/v1
China: https://api.rollinggo.cn/v1

Authentication

Include your API key as a Bearer token in the Authorization header on all management requests:

Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxx

Supported Events

Subscribe to one or more of the following event types when registering your webhook:

Event	Trigger
`booking.confirmed`	A booking transitions to `confirmed` status.
`booking.failed`	A booking fails or is rejected by the carrier.
`booking.cancelled`	A booking is cancelled, either by the passenger or the carrier.
`booking.updated`	Any field on a booking record changes (e.g., schedule update, seat reassignment).

Register a Webhook

POST https://api.rollinggo.ai/v1/webhooks/register

Register an HTTPS endpoint to start receiving event notifications. You can subscribe to one or more event types in a single registration.

Request Parameters

string

required

The fully qualified HTTPS URL of your endpoint that will receive event POST requests (e.g., https://yourapp.example.com/webhooks/rollinggo). Plain HTTP URLs are not accepted.

array

required

An array of event type strings to subscribe to. Must contain at least one entry. See Supported Events for valid values.

string

A shared secret string used to generate HMAC-SHA256 signatures on every delivery. Strongly recommended — see Verifying Webhook Signatures for how to use it.

Example Request

{
  "url": "https://yourapp.example.com/webhooks/rollinggo",
  "events": ["booking.confirmed", "booking.cancelled"],
  "secret": "your_webhook_secret"
}

Example Response

{
  "status": "ok",
  "webhookId": "wh_abc789",
  "url": "https://yourapp.example.com/webhooks/rollinggo",
  "events": ["booking.confirmed", "booking.cancelled"]
}

Response Fields

string

"ok" on a successful registration.

string

A unique identifier for this webhook registration. Save this — you need it to remove the webhook later with DELETE /webhooks/{id}.

string

The registered endpoint URL, echoed back for confirmation.

array

The list of event types this webhook is subscribed to.

Webhook Payload

RollingGo delivers a POST request to your registered URL for each matching event. Every payload follows this structure:

{
  "event": "booking.confirmed",
  "timestamp": "2025-09-01T11:45:00Z",
  "data": {
    "bookingId": "bk_XYZ9012",
    "bookingStatus": "confirmed",
    "pnr": "RGX7AB"
  }
}

string

The event type that triggered this delivery (e.g., booking.confirmed).

string

ISO 8601 UTC timestamp of when the event was generated on RollingGo’s servers.

object

The event payload. For booking events, this contains bookingId, bookingStatus, and pnr.

Verifying Webhook Signatures

When you provide a secret during registration, RollingGo signs every outgoing request with HMAC-SHA256 and includes the hex-encoded signature in the X-RollingGo-Signature header. Always verify this signature before processing the event payload. To verify the signature, compute an HMAC-SHA256 of the raw request body using your secret, then compare it to the value in the header. Use a timing-safe comparison to prevent timing attacks:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Always verify webhook signatures before processing events to ensure requests genuinely originate from RollingGo and have not been tampered with in transit.

Remove a Webhook

DELETE https://api.rollinggo.ai/v1/webhooks/{id}

Deregister a webhook to stop receiving event deliveries to that endpoint.

Path Parameters

string

required

The webhookId returned when you registered the webhook (e.g., wh_abc789).

Example Request

DELETE https://api.rollinggo.ai/v1/webhooks/wh_abc789
Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxx

Error Responses

HTTP Status	Code	Description
400	`invalid_params`	A required field is missing or a value is in an invalid format (e.g., a non-HTTPS URL or an unrecognised event type).
401	`unauthorized`	The API key is missing, invalid, or revoked.
404	`not_found`	The `webhookId` does not exist or does not belong to your account.
429	`rate_limited`	You have exceeded your rate limit. Slow down and retry.

Delivery and Retries

Your webhook endpoint must respond with an HTTP 200 status within 5 seconds of receiving a delivery. If it does not, RollingGo marks the attempt as failed and retries automatically. Failed deliveries are retried up to 3 times using exponential backoff.

To keep delivery latency low, accept the webhook payload and enqueue it for asynchronous processing rather than performing heavy work in the request handler before responding.

Overview

MCP Endpoints

RollingGo Webhooks — Register, Verify, and Handle Events

Authentication

Supported Events

Register a Webhook

Request Parameters

Example Request

Example Response

Response Fields

Webhook Payload

Verifying Webhook Signatures

Remove a Webhook

Path Parameters

Example Request

Error Responses

Delivery and Retries

​Authentication

​Supported Events

​Register a Webhook

​Request Parameters

​Example Request

​Example Response

​Response Fields

​Webhook Payload

​Verifying Webhook Signatures

​Remove a Webhook

​Path Parameters

​Example Request

​Error Responses

​Delivery and Retries

Authentication

Supported Events

Register a Webhook

Request Parameters

Example Request

Example Response

Response Fields

Webhook Payload

Verifying Webhook Signatures

Remove a Webhook

Path Parameters

Example Request

Error Responses

Delivery and Retries