Implementation Guides

Receiving Webhooks

note

We're currently testing webhooks with some initial users. If you'd like to try webhooks for yourself, please drop us an email at help@duffel.com.

Overview

In this guide, you'll learn how to set up and handle webhooks in your Duffel integration.
After you've set up webhooks, you'll receive notifications about events that happen in your Duffel account - for example, when an airline has a schedule change affecting one of your orders.
We'll send these events to your server, and then you can process them and take action automatically - for example updating your database or emailing a customer.
We'll go through three simple steps to set this up:
  • Build a simple webhook receiver in Python

  • Create a webhook

  • Send a test event to our webhook

Building a simple webhook receiver in Python

Let's start by creating a server, running locally on our machine, that can receive event notifications.
For this example, we'll write our server in Python 3, but you can use any modern programming language.
We'll assume that you have Python 3 and pip installed. We'll use Flask to quickly build a server. You can install Flask with pip install flask.
Once you have Flask installed, copy the code below and paste it into an app.py file. After you've set up your webhook in step 2, we'll replace <your-generated-webhook-secret> with your webhook's secret.
import json
import hmac
import hashlib
import base64
from flask import Flask, jsonify, request
app = Flask(__name__)
# Secret as bytes, ready for comparison
secret = b"<your-generated-webhook-secret>"
# Our route that will receive the webhooks from Duffel's servers
@app.route('/webhooks', methods=['POST'])
def hello_world():
if not compare(secret, request):
print('⚠️ Unsafe payload')
return jsonify(success=True)
# Sample event:
# {'updated_at': None, 'type': 'ping.triggered', 'object': 'ping', 'live_mode': False, 'inserted_at': None, 'identity_organisation_id': 'org_0000A5IcgBRqte1uoxkDU8', 'id': 'eve_0000A5O5f2N91XniqO9DdY', 'data': {'object': {}, 'changes': None}}
event = None
try:
# Get the payload as JSON
event = request.json
print('ℹ️ Parsed event')
except:
print('⚠️ Webhook error while parsing basic request.' + str(e))
return jsonify(success=False)
# Handle the event
if event and event['type'] in ['order.updated', 'ping.triggered']:
print('ℹ️ Event type: ' + event['type'])
else:
# Unexpected event type
print('⚠️ Unhandled event type {}'.format(event['type']))
return jsonify(success=True)
print('✅Handled event!')
return jsonify(success=True)
# Compare the request's payload with our secret to verify that it was sent
# from Duffel, and not from a malicious actor.
def compare(secret, request):
# Get the payload as bytes so that we can construct the signature from
# raw/unparsed data
raw_payload = request.get_data()
# Format:
# t=1616202842,v1=8aebaa7ecaf36950721e4321b6a56d7493d13e73814de672ac5ce4ddd7435054
raw_signature = request.headers['X-Duffel-Signature']
pairs = list(map(lambda x: x.split('='), raw_signature.split(',')))
t = pairs[0][1]
v1 = pairs[1][1]
# Recreate the signature
local_signature = signature(secret, raw_payload, t)
# Use a secure comparison function to check that they're the same
return hmac.compare_digest(v1, local_signature)
# Generate a signature
def signature(secret, payload, timestamp):
# We need the signed payload as bytes
signed_payload = timestamp.encode() + b"." + payload
# The signature in bytes
signature = hmac.new(secret, signed_payload, hashlib.sha256).digest()
# Base16 encode the signature, in lowercase, then decode to a string
return base64.b16encode(signature).lower().decode()
The application is very simple. The comments throughout explain the flow of how we process a received notification.
You can run this application on port 4567 with a simple command:

Shell

FLASK_ENV=development FLASK_RUN_PORT=4567 FLASK_APP=app.py flask run
You'll need to expose your application to the internet to be able to receive events from Duffel. The simplest way to do this on your local machine is to use ngrok, which is free to download across all major operating systems.
Once you've installed ngrok, you can run it from the command line and expose port 4567 to the internet with the following command:

Shell

ngrok http 4567
With ngrok running, you'll need to copy the URL it gives you so you can pass that to Duffel and we can send you events.
You should see output from ngrok with a line that looks something like $ Forwarding http://be3baxdc.ngrok.io -> 127.0.0.1:4567. You should copy the http://be3baxdc.ngrok.io part.
You'll need to keep the Python script and ngrok running for the next steps of this guide.

Creating a webhook

Next, we need to use the Duffel API to create a new webhook pointing to our webhook receiver.
Duffel can send a range of different kinds of "event" via a webhook. Let's start by creating a webhook which is subscribed to the order.updated event. This event will be triggered, and we'll send a request to your webhook, when an order is "schedule changed" by an airline.
You can use a request like this to create a webhook - you'll need to replace <YOUR_ACCESS_TOKEN> with your access token for the Duffel API, and the url with the URL you got from ngrok above:

Shell

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.updated"
]
}
}'
You'll get back a response like this:
{
"meta": null,
"data": {
"url": "http://be3baxdc.ngrok.io/webhooks",
"secret": "54vFWvaSbbzYpxXPeB4YEw==",
"id": "sev_0000A5TK3psWyzKIU2La52",
"events": [
"order.updated"
],
"created_at": "2021-03-22T15:14:42.127734Z",
"active": true
}
}
You'll see that the webhook is currently active. You can deactivate a webhook using the update a webhook endpoint in the API.
You must write down the returned secret as it's only available at the time when you create a webhook. You'll never be able to see it again.
You'll need to take that secret and replace <your-generated-webhook-secret> in your Python code above with it, and then restart the application.
Note that you'll have specific, separate webhooks for Duffel's live mode and test mode. When you create a webhook, its mode will be determined by the access token you use. live_mode will be set to true if you create the webhook using a live mode access token. It'll be set to false if you use a test mode access token. You should start in test mode.

Sending a test event to our webhook

We now have our local webhook receiver running and we've created a webhook in Duffel to send events to that receiver. Congratulations! 🎉 The next step is to make sure it works.
We have an API endpoint that allows you to trigger a ping event to your webhook. To trigger a ping, you'll need the ID for the webhook (which was returned when you created your webhook - for example sev_0000A5TK3psWyzKIU2La52). With that, you can send a request to Duffel to trigger the ping event:

Shell

curl -X POST --compressed "https://api.duffel.com/air/webhooks/id/
$WEBHOOK_ID
/actions/ping" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer
$YOUR_ACCESS_TOKEN
" \
-d '{}'
You'll need to replace $YOUR_ACCESS_TOKEN with your Duffel access token and $WEBHOOK_ID with the ID of your webhook.
If your webhook was configured successfully and your code was running and accessible to the internet, your local Python server should output ✅ Handled event!.

What's next?

You've created a webhook which subscribes to the order.updated event, so you'd receive a push whenever an order is changed - for example due to a schedule change on the airline's side.
An order.updated webhook looks like this:
{
"created_at":"2021-04-22T13:13:18.420272Z",
"data":{
"object":{
"id":"ord_0000A6VMpoIRpFpJYwXfyy"
}
},
"id":"eve_0000A6VP9fgKxAccTSKWUy",
"live_mode":false,
"object":"order",
"type":"order.updated"
}
In your code, you should look at the type of events that you receive and handle that appropriately.
For example, you might want to handle an order.updated webhook by retrieving the order from the API using its data.object.id, updating your database and sending an email to the customer about the changes.