Webhooks

Introduction 

Webhooks allow you to get automated notifications about specific events on Distribusion side. Currently, we are supporting the following: 

• Booking: Notification for new bookings. 
• Cancellation: Notification for new cancellations.
• Amendment: Notification for new amendments.

In each case, we ensure immediate information about the actual booking, cancellation and amendment so the retailer can use the information received to automate their internal flows. For example, in case of a new booking a subsequent call can be made to the /bookings/{booking_id} endpoint to get the full booking details. Or in case of a carrier cancellation the retailer can also update the booking in their own data base to have status cancelled, process refunds if needed, as well as informing the customer or their internal customer support. 

Retry Mechanism

A webhook retry is a process that resends a failed webhook notification. Retrying ensures higher reliability and successful delivery of event notifications. At Distribusion, retries are implemented with a schedule of 60 seconds, repeated up to 5 times. This approach helps ensure important messages, like cancellation events, are delivered even if the initial attempt fails.

Request Details

Headers

The headers of the request include relevant information about the event, with the most important information being:

• x-distribusion-event: The type of the event, e.g. "ping", "cancellation", "booking" or “amendment”.
• x-distribusion-delivery: The uuid of this delivery, can be used to look up the event via api.
• x-distribusion-signature: The SHA256 HMAC hex digest of the secret key and body.

Body Content 

The request body is json-api serialized data of the event. Types of events:

1. Ping: In the case of a ping, it's empty.
2. Booking: In case of a booking, the response includes the booking id. To retrieve the full booking details make an additional request to the /bookings/{booking_id} endpoint.
3. Cancellation: In case of a cancellation, the response also includes the cancellation id and the booking_id. besides other info such as price, fee and refund amounts. To retrieve other booking and cancellation details make an additional request to the /bookings/{booking_id} endpoint.
4. Amendment: In case of an amendment, the response includes the amendment id, the booking_id of the original booking that originated the amendment and new_booking_id of the new booking created as a result of the amendment. To retrieve the full booking details of each booking make an additional request to the /bookings/{booking_id} endpoint or use the amendment id in the /amendments/{amendment_id} endpoint.

You should always use the x-distribusion-event header to know how to interpret the body response. 

Securing Your Endpoint 

When Distribusion configures your webhook, we share a secret key in a format such as 358fa65d-fe8c-489c-abd1-644a31abb46b. This secret key encrypted with SHA256 HMAC will appear under the x-distribusion-signature header and can used to verify that the requests to your endpoint are really from Distribusion.

Booking Request 

Sample Headers (main items)

• x-distribusion-event: booking
• x-distribusion-delivery: 5167cf32-e877-465a-b508-59a7eba42bb9
• x-distribusion-signature: sha256=f0e38064551fa02e111ed202c269cb6c1d79d587d8caf4261e736298adf1a145

Sample Body Content 

 
{
  "data": {
    "id": "BAjb86Bc-qHIbpP78M8Z_g",
    "type": "bookings",
    "attributes": {
      "id": "BAjb86Bc-qHIbpP78M8Z_g",
      "created_at": "2025-03-18T17:07",
      "utm_params": null,
      "retailer_booking_number": null,
      "retailer_partner_number": "222222",
      "distribusion_booking_number": "HX1GQF",
      "marketing_carrier_booking_numbers": [
        "DEMOBNUM01"
      ]
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Cancellation Request

Sample Headers (main items)

• x-distribusion-event: cancellation
• x-distribusion-delivery: 9a0ae763-47bf-4801-8463-9bb43e222e85
• x-distribusion-signature: sha256=e4cf1b6e2ebe610db83d8819a27dc107cb62f7b3d2994ec9f0e01519b3b4bc7f

Sample Body Content

 
{
  "data": {
    "id": "a7VAsfs0sE9AMTHCI0bpgg",
    "type": "cancellations",
    "attributes": {
      "fee": 0,
      "state": "confirmed",
      "reason": null,
      "created_at": "2025-01-10T14:06",
      "total_price": 2500,
      "total_refund": 2500,
      "voucher_refund": 0,
      "monetary_refund": 2500,
      "confirmation_expected_at": null
    },
    "relationships": {
      "fees": {
        "data": []
      },
      "vouchers": {
        "data": []
      }
    }
  },
  "meta": {
    "source": "Retailer",
    "currency": "EUR",
    "booking_id": "Ai7ieaOteDlQIS-RVdioxg",
    "retailer_booking_number": null,
    "retailer_partner_number": "222222",
    "distribusion_booking_number": "AIXFPC",
    "marketing_carrier_booking_numbers": [
      "RP4GBJIL"
    ]
  },
  "jsonapi": {
    "version": "1.0"
  },
  "included": []
}

Amendment Request

Sample Headers (main items)

• x-distribusion-event: amendment
• x-distribusion-delivery: 6a712051-b188-4efa-a346-9a403b60eddb
• x-distribusion-signature: sha256=2cc5383def7fdc5ef664faa497f68b4ad1fa18fb25f612a718288036f0165d41

Sample Body Content

 
{
  "data": {
    "id": "AOJIW411",
    "type": "amendments",
    "attributes": {
      "id": "AOJIW411",
      "state": "confirmed",
      "created_at": "2025-01-13T02:59",
      "delta_price": 0,
      "amendment_fee": 0
    }
  },
  "meta": {
    "locale": "en",
    "currency": "EUR",
    "booking_id": "CpYqKuAB8xGojOjusgC9TQ",
    "new_booking_id": "8-oYOfsrxThDkqxvKKGGGQ",
    "retailer_booking_number": null,
    "retailer_partner_number": "222222",
    "distribusion_booking_number": "H91FWW",
    "marketing_carrier_booking_numbers": [
      "8892213"
    ]
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Testing 

If your webhook URLs are not configured from your side yet you can test our webhooks using a test tool such as Webhook Tester.

Once the webhook URL is in place and registered with Distribusion, you can try communication by triggering a ping.

Ping

curl -X POST \ 
https: //api.distribusion.com/retailers/v4/webhooks/ping \ --header 'Content-Type: application/json' \ 
--header 'Accept: application/vnd.api+json' \ 
--header 'Api-Key: e3c3e6a6-6494-475c-bb7e-f96e2ce47d91' \ 

Response

 
{
    "data": {
        "id": "75d2de48-4e2f-405a-b835-5f0aeb6d2a19",
        "type": "webhook_deliveries"
    },
    "jsonapi": {
        "version": "1.0"
    }
}

Event Look Up

The ping is handled asynchronously, and you can look up the event with the ID: curl -X GET \ 

curl -X GET \ 
https: //api.distribusion.com/retailers/v4/webhooks/deliveries/75d2de48-4e2f-4 05a-b835-5f0aeb6d2a19 \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: application/vnd.api+json' \ 
--header 'Api-Key: e3c3e6a6-6494-475c-bb7e-f96e2ce47d91'  

Response

 
{
    "data": {
        "id": "75d2de48-4e2f-405a-b835-5f0aeb6d2a19",
        "type": "webhook_deliveries",
        "attributes": {
            "success": true,
            "event_type": "ping",
            "payload": null,
            "created_at": "2019-01-01T01:00",
            "started_at": "2019-01-01T01:00",
            "duration": 1.0,
            "request": {
                "url": "http://myhost.com/my-webhook",
                "headers": {
                    "X-Distribusion-Delivery": "75d2de48-4e2f-405a-b835-5f0aeb6d2a19",
                    "X-Distribusion-Event": "ping",
                    "X-Distribusion-Signature": "sha256=20ebc0f09344470134f35040f63ea98b1d8e414212949ee5c500429d15eab081"
                }
            },
            "response": {
                "body": "thanks",
                "headers": {
                    "Some-Response-Header-Name": "some-response-header-value"
                },
                "http_status": 201,
                "error_message": ""
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    }
}