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.

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

  • order.created: This event is sent whenever an order is created.
  • order.updated: This event is sent whenever an order is updated which is by detection of schedule changes.

Each event payload that your webhook server will receive will be structured similar to the example below, which is for an Order that was created:

{
"id": "eve_0000A4tQSmKyqOrcySrGbo",
"type": "order.created",
"object": "order",
"data": {
"object": { .. },
"changes": null
},
"live_mode": true,
"created_at": "2020-04-11 15:48:11.642000+00:00"
}
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.updated"]
id
string

Duffel's unique identifier for the webhook receiver

Example: "sev_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
secret
string

The secret used to secure the payload being sent. This will only be returned when the webhook is first created.

Example: "QKfUULLQh+8SegYmIsF6kA=="
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: "sev_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 if it's active or not

URL parameters

id
string
required

Duffel's unique identifier for the webhook receiver

Example: "sev_0000A3tQSmKyqOrcySrGbo"

Body parameters

active
boolean

The desired active status of the webhook

Example: 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.

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": {
"active": true
}
}'

Response

{
"data": {
"url": "https://www.example.com:4000/webhooks",
"updated_at": "2020-04-11T15:48:11.642Z",
"secret": "QKfUULLQh+8SegYmIsF6kA==",
"live_mode": true,
"id": "sev_0000A3tQSmKyqOrcySrGbo",
"events": [
"order.created",
"order.updated"
],
"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.

By default, it will be active.

Body parameters

events
string[]
required

The events that this webhook will be subscribed to

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

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.

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:4000/webhooks",
"events": [
"order.created",
"order.updated"
]
}
}'

Response

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