Now that we understand the basics of webhooks, let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a event webhook that will be responsible for receiving all airlock browser events.
Creating a webhook is a two-step process. You'll first need to set up how you want your webhook to behave through Airlock and what events should it listen to. After that, you'll set up your server to receive and manage the payload.
Exposing localhost to the internet
For the purposes of this tutorial, we're going to use a local server to receive messages from Airlock. So, first of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.
After installing ngrok, you can expose your localhost by running
./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567
Make a note of the
*.ngrok.io URL. We'll use it to set up our webhook.
Setting up a webhook
You can install webhooks on an organization or on a specific repository.
To set up a webhook, go to the configure page of your airlock group. From there, click Webhooks (advanced).
Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.
The payload URL is the URL of the server that will receive the webhook POST requests.
Since we're developing locally for our tutorial, we'll set it to the
*.ngrok.io URL, followed by
/payload. For example,
The content type of the payload is
application/jsoncontent type will deliver the JSON payload directly as the body of the POST request.
Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from Airlock. When you set a secret, you'll receive the X-Airlock-Signature header in the webhook POST request. For more information on how to use a secret with a signature header to secure your webhook payloads, see "Securing your webhooks."
If your "Payload URL" is a secure site (HTTPS), you will have the option to configure the SSL verification settings. By default, Airlock verifies the SSL certificate of your website when delivering webhook payloads. SSL verification helps ensure that hook payloads are delivered to your URL endpoint securely. You have the option to disable SSL verification for self-signed certificates, but we recommend keeping Enable SSL verification selected.
Turning off webhooks
By default, webhook deliveries are "On". You can choose to turn off webhook payloads by deselecting all triggers, or removing the URL.
Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on the group, which your server's payload URL intercepts and acts upon.
Since our webhook is dealing with browser events in a group, we'll click Triggers drop down and then Event.
When you're finished, click Save.
Now that you've created the webhook, it's time to set up our local server to test the webhook. Head on over to Configuring Your Server to learn how to do that.