CapData Webhooks

CapData can notify your system in real-time about important events, such as the creation of a new reservation, by sending a POST request to a URL you specify. This allows you to react instantly to the extracted data.

1. How to Set Up Your Webhook URL

To receive webhooks, you must configure your "Webhook Endpoint" in the CapData portal:

Log in to your CapData Portal.
Navigate to the Integrations section in the side menu.
Select the General Webhook option.
Enter the URL of your server that will receive the POST requests (e.g., https://myserver.com/receive-capdata-webhook).
Save the changes. From that moment on, CapData will start sending events to that URL.

Note: Your endpoint must be a public URL accessible from the internet. For local testing, you can use tools like ngrok to expose your local server.

2. Webhook Payload Structure

When an event occurs, we will send a POST request to your URL with a JSON body. The payload structure always contains information about the event, the account context, and who originated the action.

Example: `new_flight_reservation_from_extension` Event

This event is triggered when a new reservation is extracted through the General API (e.g., Chrome extension).

Example JSON Payload

{
    "event_type": "new_flight_reservation_from_extension",
    "reservation_data": [
        {
            "booking_code": "XYZ123",
            "passenger_name": "MARIA LOPEZ",
            "departure_date": "25/12/2025",
            "airline": "Vueling"
            // ... other reservation data
        }
    ],
    "webhook_account_context": {
        "owner_id": 1,
        "owner_name": "Main Owner",
        "owner_email": "owner@email.com",
        "owner_slug": "main-owner"
    },
    "action_originator": {
        "actor_type": "agent",
        "actor_id": 101,
        "actor_name": "Support Agent",
        "actor_username": "support.agent",
        "actor_token_used": "the_agent_token_used",
        "agent_belongs_to_client_id": 15,
        "agent_belongs_to_client_name": "Demo Travel Agency",
        "agent_belongs_to_client_type": "agency"
    }
}

Example: `flight_reservation_updated` Event

This event is sent when an existing reservation is updated via /api/update_reservation. It includes a updated_at timestamp in ISO 8601 format.

Example JSON Payload – reservation update

{
  "event_type": "flight_reservation_updated",
  "reservation_data": {
    "booking_code": "ABCDEF",
    "passenger_name": "Juan Pérez García",
    "departure_date": "2025-10-15",
    "return_date": "2025-10-22",
    "airline": "Iberia",
    "price": "250.50"
    // ... other fields according to your reservation model
  },
  "updated_at": "2025-05-12T10:15:30Z",
  "webhook_account_context": {
    "owner_id": 1,
    "owner_name": "Main Owner",
    "owner_email": "owner@email.com",
    "owner_slug": "main-owner"
  },
  "action_originator": {
    "actor_type": "owner",
    "actor_id": 1,
    "actor_name": "Main Owner"
    // or "agent"/"agency" if applicable
  }
}

Payload Keys

event_type: A string that identifies the type of event (e.g., new_flight_reservation_from_extension, flight_reservation_updated).
reservation_data: An object or an array with the data of the reservations related to the event.
updated_at: (only in update events) an ISO 8601 timestamp.
webhook_account_context: Identifies the Owner to whom the webhook and the data belong.
action_originator: Details who performed the action (owner, agency, or agent).

3. Best Practices and Security

Respond quickly: Your endpoint should respond with 200 OK as soon as possible to acknowledge receipt. Process asynchronously if your logic is heavy.
Verify the origin: Currently, the platform does not send an HMAC signature by default. for enhanced security, you can protect your endpoint by requiring a custom Bearer token (e.g., in the Authorization header) or a secret parameter in the URL. If you need signature validation, contact us to enable HMAC signature headers.
Handle duplicates (idempotency): It is possible to receive the same event more than once (due to network issues or retries). Use event_type along with business identifiers (e.g., booking_code) and, if applicable, updated_at to deduplicate.

4. Recommended Headers (for your endpoint)

Although CapData sends a Content-Type: application/json, we recommend that your endpoint also:

Require its own authentication (e.g., Authorization: Bearer <your_secret>) or a token in the URL.
Log traces of the request (method, path, minimal headers, body size) for debugging.
Implement HMAC signature verification (optional, if enabled with us) using a header like X-CapData-Signature that signs the body with HMAC-SHA256 and a shared secret.

Important: If you decide to require a token or signature, configure it on your server. CapData will include what you specify in the URL (e.g., ?token=...) or can send signature headers if they are enabled for your account.

5. Idempotency and Retries

Design your handler to be idempotent:

Generate an "event key" with event_type + booking_code (or another business identifier) + updated_at when it exists.
If you have already processed that key, respond with 200 OK and finish without side effects.
In case of temporary errors on your server, return a 5xx status. It is advisable for your infrastructure to allow controlled retries.