Overview

Roam uses webhooks to send real-time notifications to your application as bookings, charges, and payments progress through their lifecycle.

Webhook notifications allow your systems to respond automatically to operational and financial events without the need for continuous polling. All webhook events are delivered as HTTP POST requests containing a JSON payload representing the latest state of the affected record at the time the event was emitted.

Configuration

To configure webhook notifications, the following information must be provided to Roam:

Parameter	Description
Webhook Endpoint URL	The HTTPS endpoint where Roam should deliver webhook events
Webhook Secret Key	A secret key used to generate and verify webhook request signatures

The webhook secret key is provided by your system and securely stored within the Roam platform for signature generation.

All webhook deliveries are sent to a single configured endpoint.

Webhook Delivery

Webhooks are delivered as HTTP POST requests with a JSON request body.

Your endpoint must:

• Accept inbound HTTPS POST requests

• Return an HTTP 200 OK response to acknowledge successful receipt

The following headers are included:

Header	Description
Content-Type	Always application/json
x-timestamp	Unix timestamp in milliseconds
x-signature	Shared secret used to verify the request source

Deliveries are asynchronous and may be delayed by several minutes while related processing and calculations are completed within the platform. Each webhook also contains a unique event identifier to support idempotent processing and duplicate handling within your application.

Security Verification

Webhook requests include a shared secret in the x-signature header to allow verification that the request originated from Roam.

All webhook requests are delivered over HTTPS and signatures should always be verified before parsing or processing JSON payloads.

Responding to Webhooks

Your endpoint should acknowledge webhook deliveries immediately by returning an HTTP 200 OK response before performing longer-running business logic asynchronously.

This helps prevent delivery delays and unnecessary retries.

Event Types

Roam publishes webhook events for bookings, charges, and payments. All event types are delivered to the same configured webhook endpoint.

Event Type	Description
booking.updated	Emitted when a booking record is updated
charge.updated	Emitted when a charge record is updated
payment.created	Emitted when a payment record is created
payment.updated	Emitted when a payment record is updated

Event Payloads

Webhook payloads contain the latest state of the affected record at the time the event was emitted.

Payloads are delivered as JSON within the request body. It is recommended treating webhook payloads as the source of truth for the event at the time it was published.

The following examples show representative payloads for each event type.

Booking Event Example

{
  "Record_Link": "https://partner.roam.global/booking/BKG-10248",
  "Itinerary_Link": null,
  "Travel_End_Date": "2026-09-18",
  "Travel_Start_Date": "2026-09-05",
  "Passengers": 2,
  "Client_Last_Name": "Walker",
  "Client_First_Name": "Emma",
  "Client_Email": "emma.walker@example.com",
  "Quote_Reference": "Q-20260905",
  "Booking_Summary_Link": "https://partner.roam.global/summary/SMRY-10248",
  "Funds_Outstanding": 1850.50,
  "Funds_Received": 549.50,
  "Payment_Suggestion": 100,
  "Balance_Due_Date": "2026-08-15",
  "Deposit_Due_Date": "2026-06-01",
  "Balance_Total": 1850,
  "Deposit_Total": 550,
  "Booking_Total": 2400,
  "Confirmed": true,
  "Proceeding": true,
  "TXN_Currency": "USD",
  "Validity_Date": "2026-06-01",
  "Booking_Id": "BKG-10248",
  "message": "Booking has successfully been updated.",
  "success": true
}

Charge Event Example

{
  "Paid_Out": false,
  "Completed": false,
  "Booked": true,
  "Supplier_3_Amount": 0,
  "Supplier_2_Amount": 0,
  "Supplier_1_Amount": 8200,
  "Beneficiary_3_Id": null,
  "Beneficiary_2_Id": null,
  "Beneficiary_1_Id": "SUPPLIER-ZAR-001",
  "Due_Date": "2026-06-01",
  "Type": "Deposit",
  "BSE_Currency": "ZAR",
  "BSE_Total": 8200,
  "TXN_Total": 550,
  "Charge_Id": "CHG-20814",
  "Booking_Id": "BKG-10248",
  "message": "Charge has successfully been updated.",
  "success": true
}

Payment Event Example

{
  "Amount": 550,
  "Currency": "USD",
  "Type": "Deposit",
  "Method": "Bank Transfer",
  "Received_Date": "2026-06-02",
  "Payment_Id": "PMT-48372",
  "Booking_Id": "BKG-10248",
  "message": "Payment has successfully been created.",
  "success": true
}