Quickstart: Third party event routing with Hookdeck

In this quickstart, you'll learn how to use Hookdeck to integrate two third-party services. In this case, you'll receive a webhook from GitHub and trigger an SMS message using Twilio. The practices demonstrated here can be applied when integrating any number of third-party APIs and services.

You will walk through these steps:

1. Ensure you have some prerequisites in place before you begin
2. Set up a Connection within Hookdeck
3. Receive a webhook from GitHub in Hookdeck
4. Transform the GitHub webhook event payload into a Twilio SMS request payload
5. Filter the events so that only new GitHub issues are processed
6. Fully integrate GitHub and Twilio using Hookdeck

Before you begin

Create a connection

A Connection consists of a Source, optional Rules, and a Destination. It defines the flow of the webhook event, from receipt through to delivery.

curl --location 'https://api.hookdeck.com/2023-07-01/connections' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_PROJECT_API_KEY' \
--data '{
  "name": "send-sms-on-new-issue",
  "source": {
    "name": "github"
  },
  "destination": {
    "name": "twilio",
    "url": "https://mock.hookdeck.com"
  }
}'

{
  "id": "web_oPymMJ0isyuS",
  "team_id": "tm_SAN9hnAiGLbI",
  "disabled_at": null,
  "updated_at": "2023-11-18T16:52:43.897Z",
  "created_at": "2023-11-18T16:52:44.096Z",
  "paused_at": null,
  "name": "send-sms-on-new-issue",
  "rules": [],
  "description": null,
  "destination": {
    "id": "des_wNYxQXpkYHcM",
    "team_id": "tm_SAN9hnAiGLbI",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2023-11-18T16:52:43.897Z",
    "created_at": "2023-11-18T16:52:43.903Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "twilio",
    "http_method": null,
    "auth_method": { "type": "HOOKDECK_SIGNATURE", "config": {} },
    "description": null
  },
  "source": {
    "id": "src_KUdNgMByl0uP",
    "team_id": "tm_SAN9hnAiGLbI",
    "disabled_at": null,
    "updated_at": "2023-11-18T16:52:43.897Z",
    "created_at": "2023-11-18T16:52:43.905Z",
    "name": "github",
    "allowed_http_methods": ["POST", "PUT", "PATCH", "DELETE"],
    "custom_response": null,
    "description": null,
    "url": "{YOUR_SOURCE_URL}",
    "verification": null
  },
  "full_name": "github -> send-sms-on-new-issue"
}

Receive a webhook from GitHub in Hookdeck

The Source URL should receive a webhook from GitHub whenever any event related to a GitHub issue for a repo occurs.

In the vast majority of situations you should also set a secret used to verify your webhook payload. Hookdeck provides in-built support for webhook signature verification. However, for the purposes of this quickstart, you can skip this step.

With the webhook configured, you can test it by creating a new issue in the GitHub repository.

The webhook event will be sent to Hookdeck.

You will see the event with the GitHub webhook payload, including the action of opened and the issue details.

Transform the GitHub webhook event payload

In this next step, you will transform the GitHub webhook event payload into a Twilio SMS request payload using Hookdeck transformations.

This opens the New Transformations page. Within this page you can see:

• Input - the payload and metadata for the input request
• Output - the payload and metadata from the result of the transformation
• Diff - the difference between the input and output payloads
• Code editor - the code used to transform the input payload into the output payload
• Console - the console output from the transformation code

const TWILIO_ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
const FROM_NUMBER = process.env.FROM_NUMBER;
const TO_NUMBER = process.env.TO_NUMBER;

addHandler('transform', (request, context) => {
  request.headers['content-type'] = 'application/x-www-form-urlencoded';

  // URL set in destination:
  // https://api.twilio.com/2010-04-01/Accounts/
  request.path = `/${TWILIO_ACCOUNT_SID}/Messages.json`;

  request.body = {
    From: FROM_NUMBER,
    To: TO_NUMBER,
    Body: 'New issue created\n' +
    request.body.issue.title + '\n\n' +
    request.body.issue.html_url
  };

  return request;
});

To transform the GitHub webhook event payload into a Twilio SMS request payload, the transformation code does the following:

1. Change the Content-Type header from application/json to application/x-www-form-urlencoded
2. Update the destination path for the Twilio API to include the Twilio Account SID
3. Build the request body to contain the From, To, and Body parameters

You will see the updated event payload in the Output section.

Filter the events for new GitHub issues only

As things stand, this will send an SMS message for every GitHub issue event. However, you only want to send an SMS message when a new issue is created.

Go back into the transformation and if the action is not opened, return the request untouched. You will filter out in the next part of the process.

const TWILIO_ACCOUNT_SID = process.env.TWILIO_ACCOUNT_SID;
const FROM_NUMBER = process.env.FROM_NUMBER;
const TO_NUMBER = process.env.TO_NUMBER;

addHandler('transform', (request, context) => {
  if(request.body.action !== 'opened') {
    return request;
  }
  
  request.headers['content-type'] = 'application/x-www-form-urlencoded';

  // URL set in destination:
  // https://api.twilio.com/2010-04-01/Accounts/
  request.path = `/${TWILIO_ACCOUNT_SID}/Messages.json`;

  request.body = {
    From: FROM_NUMBER,
    To: TO_NUMBER,
    Body: 'New issue created\n' +
      request.body.issue.title + '\n\n' +
      request.body.issue.html_url
  };

  return request;
});

With the transformation update in place to detect the action type, you can now create a filter rule to filter out GitHub events.

{
  "action": {
    "$exist": false
  }
}

Fully integrate GitHub and Twilio using Hookdeck

The Hookdeck connection now transforms the GitHub webhook event payload into a Twilio SMS request payload and filters out any GitHub events that are not opened issues.

The final steps are to update the Destination URL to point to the Twilio API endpoint, and set your Twilio API credentials.

Remember that the transformation appends the Twilio Account SID to the Destination URL via the request.path property.

As before, you can check this in both the Hookdeck dashboard Requests and Events sections.

What you have learned

By following this quickstart, you set up a Connection with Hookdeck and tested receiving webhooks from GitHub with Hookdeck with the requests sent to the Hookdeck Mock API endpoint.

You then used a Hookdeck transformation to transform the GitHub webhook event payload into a Twilio SMS request payload, including updating the request.path to include the Twilio Account SID.

You also used a Hookdeck filter to filter out GitHub events that are not opened issues.

Finally, you updated the Destination URL to point to the Twilio API endpoint, making use of Hookdeck's in-built support for customized destination auth, to complete the GitHub and Twilio integration using Hookdeck.

Where next?

You've just scratched the surface of Hookdeck. So, try out the following features:

• Authenticate the sending of webhooks by adding source authentication.
• Set up a rate limit on your Destination to adhere to the API rate limit of the destination provider's API.
• Define your retry logic for those occasions when there are problems with the destination's API.
• Create a second connection that uses the same source to integrate with another third-party service. For example, logging GitHub issues to a database.