GlobalBedBank Webhooks

GlobalBedBank webhooks let your application react to booking activity in real time without polling. When a booking event occurs, GlobalBedBank sends an HTTP POST request to the webhook URL configured for your agent account.

Your endpoint should process the payload and return a 2xx response to acknowledge delivery.

When To Use Webhooks

Use webhooks when you need to:

Keep your booking records in sync with GlobalBedBank.

Trigger confirmation, support, CRM, analytics, or fulfillment workflows.

Monitor booking success and booking failures programmatically.

If you only need booking data on demand, direct API calls are usually enough. If your application needs to react to booking changes as they happen, use webhooks.

Configure Your Endpoint

Provide GlobalBedBank with a publicly reachable webhook URL for your agent account.

Requirements:

The URL must accept POST requests.

The URL must accept JSON request bodies.

The URL should respond within 10 seconds.

The URL should return a 2xx status code after successfully receiving the event.

The URL should use HTTPS in production.

Example endpoint:

https://example-agent.com/webhooks/globalbedbank

Supported Events

GlobalBedBank currently forwards these booking events to agent webhook URLs:

Event	Description	Typical Use
`booking.book`	A booking was confirmed successfully.	Mark the booking as confirmed, send confirmation messages, or start fulfillment.
`booking.book_error`	A booking confirmation attempt failed.	Alert support teams, update checkout state, or trigger recovery workflows.

More booking lifecycle events may be added later. Your handler should ignore unknown event_name values safely.

Delivery Flow

A booking event occurs in GlobalBedBank.

GlobalBedBank resolves the booking and the agent account.

GlobalBedBank posts the event payload to the agent's configured webhook URL.

Your endpoint returns a 2xx response after receiving the event.

Webhook delivery is asynchronous. A successful booking API response and webhook delivery do not need to happen in the same request cycle.

Payload Structure

Each webhook request contains a JSON object with a consistent top-level envelope:

{
  "event_id": "evt_123",
  "event_name": "booking.book",
  "request": {
    "clientReference": "booking-reference"
  },
  "response": {
    "bookingId": "gbb-booking-123",
    "supplier": "globalbedbank",
    "supplierBookingName": "globalbedbank"
  },
  "sandbox": true
}

Top-level fields:

Field	Type	Description
`event_id`	string	Unique event identifier. Store this value for deduplication.
`event_name`	string	Event type, such as `booking.book` or `booking.book_error`.
`request`	object	Request context associated with the booking event.
`response`	object	Response context associated with the booking event.
`sandbox`	boolean	`true` for sandbox activity and `false` for production activity.

Booking Confirmation

For booking.book, the payload indicates that the booking has been confirmed. Use this event to update your internal booking record and trigger customer-facing confirmation workflows.

Example:

{
  "event_id": "evt_booked_001",
  "event_name": "booking.book",
  "request": {
    "clientReference": "agent-booking-123"
  },
  "response": {
    "bookingId": "gbb-booking-789",
    "supplier": "globalbedbank",
    "supplierBookingName": "globalbedbank"
  },
  "sandbox": false
}

Booking Failure

For booking.book_error, the payload indicates that a booking confirmation attempt failed. Use this event to notify support, update the booking status in your system, or guide the customer back into a recovery flow.

Example:

{
  "event_id": "evt_book_error_001",
  "event_name": "booking.book_error",
  "request": {
    "clientReference": "agent-booking-123"
  },
  "response": {
    "message": "Booking could not be confirmed",
    "supplier": "globalbedbank",
    "supplierBookingName": "globalbedbank"
  },
  "sandbox": false
}

Idempotency

Webhook delivery should be treated as at-least-once. Your endpoint may receive the same event more than once if delivery is retried.

Recommended handling:

Store each processed event_id.

If the same event_id arrives again, return a 2xx response without repeating side effects.

Make booking status updates idempotent.

Response Handling

Return a 2xx response after your application has accepted the webhook.

Example response:

If your endpoint returns a non-2xx response or times out, GlobalBedBank may retry delivery.

Security Recommendations

Use HTTPS for production webhook URLs.

Validate that incoming requests use the expected payload shape.

Log event_id, event_name, and your internal booking reference for traceability.

Avoid logging full guest or payment details.

Make webhook processing asynchronous if your downstream workflow can take more than a few seconds.

Webhooks

GlobalBedBank Webhooks#

When To Use Webhooks#

Configure Your Endpoint#

Supported Events#

Delivery Flow#

Payload Structure#

Booking Confirmation#

Booking Failure#

Idempotency#

Response Handling#

Security Recommendations#