Webhooks

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Webhooks are used to automatically receive notifications of events that happen. For example, when an order has a schedule change.

Once you receive an event on your server, you can process and act on it as you need.

Events

We'll progressively add more events. The currently supported events are:

  • order.created: This event is sent whenever an order is created. An example response for this event type:
{
"id": "wev_0000A4tQSmKyqOrcySrGbo",
"api_version": "beta",
"type": "order.created",
"data": {
"object": { .. },
},
"live_mode": true,
"idempotency_key": "ord_0000ABd6wggSct7BoraU1o",
"created_at": "2020-04-11 15:48:11.642000+00:00"
}
  • order.airline_initiated_change_detected: This event is sent whenever we detect an airline-initiated schedule changes to your order. An example response for this event type:
{
"id": "wev_0000A4tQSmKyqOrcySrGbo",
"api_version": "beta",
"type": "order.airline_initiated_change_detected",
"data": {
"object": { .. },
"changes": { .. },
},
"live_mode": true,
"idempotency_key": "aic_0011AJSACO83RgsiSySpzH",
"created_at": "2020-03-11 12:18:12.642000+00:00"
}

The api_version represents the version of our API that produced the data property.

System guarantees

Duffel's webhooks system guarantees the following properties:

  • It makes at least one delivery attempt per event.
  • Events are not delivered in any particular order.
  • Events are sent at least once.
  • Failed deliveries are retried for 72 hours on an exponetial backoff policy.

It also has the following security properties:

  • It always makes HTTPS requests.
  • It Signs the events.
active
boolean

Whether the webhook receiver is actively being notified or not

Example: true
created_at
datetime

The ISO 8601 datetime at which the order change was created

Example: "2020-04-11T15:48:11.642Z"
events
string[]

The events that this webhook will be subscribed to

Example: ["order.created","order.airline_initiated_change_detected"]
id
string

Duffel's unique identifier for the webhook receiver

Example: "end_0000A3tQSmKyqOrcySrGbo"
live_mode
boolean

The live mode that the webhook was created in. It will only receive events for that same live mode. For example, you won't receive order.created events for orders that you created in the sandbox, if your webook is for live_mode: true.

Example: true
updated_at
datetime

The ISO 8601 datetime at which the order change was updated

Example: "2020-04-11T15:48:11.642Z"
url
string

The URL where your webhook will be received

Example: "https://www.example.com:4000/webhooks"

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Send a ping, a "fake event" notification, to a webhook

URL parameters

id
string
required

Duffel's unique identifier for the webhook receiver

Example: "end_0000A3tQSmKyqOrcySrGbo"

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Endpoint

POST https://api.duffel.com/air/webhooks/{id}/actions/ping

Request

curl -X POST --compressed "https://api.duffel.com/air/webhooks/{id}/actions/ping" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

No response body

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Update a webhook

URL parameters

id
string
required

Duffel's unique identifier for the webhook receiver

Example: "end_0000A3tQSmKyqOrcySrGbo"

Body parameters

active
boolean

The desired active status of the webhook

Example: true
url
string

The desired url of the webhook

Example: "https://example.com/duffel/webhook"

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Endpoint

PATCH https://api.duffel.com/air/webhooks/{id}

Request

curl -X PATCH --compressed "https://api.duffel.com/air/webhooks/{id}" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
"data": {
"url": "https://example.com/duffel/webhook",
"active": true
}
}'

Response

{
"data": {
"url": "https://www.example.com:4000/webhooks",
"updated_at": "2020-04-11T15:48:11.642Z",
"live_mode": true,
"id": "end_0000A3tQSmKyqOrcySrGbo",
"events": [
"order.created",
"order.airline_initiated_change_detected"
],
"created_at": "2020-04-11T15:48:11.642Z",
"active": true
}
}

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Retrieve a paginated list of webhooks

Query parameters

limit
integer

The maximum number of records to return per page. Defaults to 50. May be set to any integer between 1 and 200. For more information on how to paginate through records, see the Pagination section.

Example: 1
Default value: 50
before
string

A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
after
string

A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Endpoint

GET https://api.duffel.com/air/webhooks

Request

curl -X GET --compressed "https://api.duffel.com/air/webhooks?limit=1&before=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&after=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
"meta": {
"limit": 50,
"after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
},
"data": [
{
"url": "https://www.example.com:4000/webhooks",
"updated_at": "2020-04-11T15:48:11.642Z",
"live_mode": true,
"id": "end_0000A3tQSmKyqOrcySrGbo",
"events": [
"order.created",
"order.airline_initiated_change_detected"
],
"created_at": "2020-04-11T15:48:11.642Z",
"active": true
}
]
}

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

To start receiving notifications of events, you'll need to create a webhook that details the server that will receive the notifications. The webhook will be created in live mode or test mode based on the access token you're using. If you're using a test mode access token, the webhook will be created in test mode and will receive events related to test mode resources. If you're using a live mode access token, it'll receive events related to live mode.

Duffel only allows one webhook to be defined per live mode value, basically your organisation can only have one url with live_mode: true and another with live_mode: false.

To ensure the highest level of security we run some checks on the URL we receive, the URL must be for an https server, we do not accept IP addresses and some URLs are blacklisted (e.g. https://localhost).

By default, the webhook will be active.

Body parameters

events
string[]
required

The events that this webhook will be subscribed to

Example: ["order.created","order.airline_initiated_change_detected"]
url
string
required

The URL where your webhook will be received

Example: "https://www.example.com/webhooks"

Preview

This is not yet finalised. It may change or be removed or be not yet accessible. This documentation is designed to give you an idea of features we'll be adding to our API in the future.

Endpoint

POST https://api.duffel.com/air/webhooks

Request

curl -X POST --compressed "https://api.duffel.com/air/webhooks" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
"data": {
"url": "https://www.example.com/webhooks",
"events": [
"order.created",
"order.airline_initiated_change_detected"
]
}
}'

Response

{
"data": {
"secret": "QKfUULLQh+8SegYmIsF6kA==",
"url": "https://www.example.com:4000/webhooks",
"updated_at": "2020-04-11T15:48:11.642Z",
"live_mode": true,
"id": "end_0000A3tQSmKyqOrcySrGbo",
"events": [
"order.created",
"order.airline_initiated_change_detected"
],
"created_at": "2020-04-11T15:48:11.642Z",
"active": true
}
}