All Guides

How to Receive Webhooks on HTTP Endpoints

Published · Updated

You want to receive webhooks to an HTTP endpoint without having to set up any infrastructure for monitoring, queuing, or retrying webhooks.

In this guide we will go through the basics to get you receiving your first webhook events using Hookdeck, and then go over a simple tutorial on how to set up Hookdeck for GitHub webhooks.

Getting started with Hookdeck UI to receive webhooks

Setting up your webhook connection

The first step is to create a connection which indicates to Hookdeck where you are expecting your webhooks to be delivered. A connection consists of the following:

ComponentExplanation
SourceLabel for your webhook.
Destinationhere you want to receive your webhooks. A Destination can be either an HTTP endpoint or your localhost. [Read our tutorial to receive webhooks to your local server using Hookdeck's CLI.]
RulesetAutomatic retry and alerts. We will not explore ruleset in this guide, as it is not necessary for receiving webhooks but you can find more information here

Receiving your webhook URL

After creating your connection, you will receive a webhook URL that is tied to your Source. You have to use this Hookdeck URL instead of your HTTP endpoint when you are setting your endpoint on your API provider.

Testing to validate it works

After setting Hookdeck's URL as your endpoint, when the API provider sends a webhook you should receive them at your destination as well as see them in Hookdeck's dashboard. You can validate the behavior by:

  • Sending a test webhook to the Hookdeck's URL
  • Triggering an event from the API provider

Getting started with Hookdeck API to receive webhooks

Create a webhook connection

When creating a connection using the API, you will need to input the following parameters:

Connection: Relationship between the webhook sender and webhook consumer

  • alias : human readable name for the connection

Source : webhook sender

  • alias: human readable name for the source
  • label: label for your source

Destination: webhook consumer

  • alias: human readable name for the destination
  • label: label for your destination
  • url: where you want to receive your webhook, either an HTTP endpoint or your localhost to receive webhooks to your local server using Hookdeck's CLI.
{
  "alias": "mysource-to-myapi",
  "source": {
    "alias": "mysource",
    "label": "mysource"
  },
  "destination": {
    "alias": "myapi",
    "label": "myapi",
    "url": "https://example.com/webhook"
  }
}

The formatting of the alias, source.alias, and destination.alias must respect `/^[a-z0-9-_]+$/`.

We will not expand on rulesets in this guide since this does not impact our ability to receive a webhook. Something to note is that when we create a connection using Hookdeck's API, the ruleset will automatically be set to default ruleset unless specified.

Receiving your webhook URL

After creating your connection, the response will include many parameters related to the webhook connection. The parameters we are interested in are:

  1. id: you will need the id to query events related to your webhook connection.
  2. url: parameter within the Source object. You have to use this URL instead of your HTTP endpoint when you are setting your webhook on your API provider.

Example of response (trimmed down to show the relevant information):

{
"id": "web_mAJbMKUCt4QDxtfTahqbub7X",
"source": {
    "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi
		},
}

Testing to validate if it works

After setting Hookdeck's URL as your endpoint, you should be receiving the webhooks the API provider sends to your destination. You can test you are receiving webhooks by:

  • Sending a test webhook to Hookdeck's URL
  • Triggering an event from the API provider

To validate if it works, you can query the API to see the events associated with the connection.

https://api.hookdeck.com/events?webhook_id=web_mAJbMKUCt4QDxtfTahqbub7X

Hookdeck UI with Github webhooks tutorial

Setting up GitHub webhook connection

In this example, we are going to subscribe to GitHub's Branch or tag creation event and then trigger a webhook to inspect the request data. Our goal is to understand the payload to eventually create an integration by writing code to respond to it.

Create a webhook connection for GitHub

Let's create a connection in Hookdeck to receive a webhook URL that we will use for GitHub's webhook registration.

  1. Select Create in the Connections view.
  2. Select "New" under Source. Set the Source Label as Github.
  3. Select "New" under Destination: Set the Destination Label as Mock API, and the Destination URL as https://mock.hookdeck.com.
  4. Select the Default Ruleset.
  5. Click Create.

hookdeck github connection

After creating the connection, our connection will look something like this. Take note of the Webhook URL for the next step.

Result github webhook connection in hookdeck

Set Hookdeck URL in GitHub

We are going to add a webhook to our GitHub repository.

  1. Go in Settings of your repository.

Github repo settings

  1. Select the "Webhooks" tab.

webhook tabs

  1. Click Add webhook.

add webhook

  1. Paste Hookdeck's webhook URL in Payload URL.
  2. Select the content type application/json.
  3. Choose "Let me select individual events" and select the Branch or tag creation event.

Github webhook event subscription

  1. Click Add webhook.

Great! We added a webhook that will send us an event every time a branch or tag is created.

Create a branch to trigger a webhook

We are now going to create a branch called New Branch from master to trigger a webhook.

Create a new branch

Validate and inspect webhook in Hookdeck

After creating a branch, the webhook becomes visible in the dashboard. When we click on the webhook, we can inspect the request's body.

Webhook event in Hookdeck Dashboard

Hookdeck API with Github webhooks tutorial

Setting up a GitHub webhook connection

In our example, we are going to subscribe to GitHub's Branch or tag creation event and then trigger a webhook to inspect the request data. Our goal is to understand the payload to eventually create an integration by writing code to respond to it.

In this tutorial I will be using Postman for my API calls.

Create a webhook connection for GitHub

Let's create a connection with Hookdeck's API to receive a webhook URL that we will use for GitHub's webhook registration.

Authentication

We need to set up the authentication to have access to Hookdeck's API.

  1. Retrieve your key under Project Secrets.

apikey

  1. Open Postman and choose the Authorization tab.
  2. Select the type Basic Auth.
  3. Enter the API as the username.

authorization postman

To send a request to create the webhook connection:

  1. Select POST.

  2. Enter the following URL https://api.hookdeck.com/connections.

  3. Select Body > raw > JSON.

  4. Enter the following payload:

    {
  "alias": "github-to-mockapi",
  "source": {
    "alias": "github",
    "label": "github"
  },
  "destination": {
    "alias": "mockapi",
    "label": "mockapi",
    "url": "https://mock.hookdeck.com"
  }
}

  5. Click send.

You should receive a response with the following parameters:

{
  "id": "web_bKvPP9qnF16kNdR1XBMtK6aJ",
  "label": "mockapi",
  "alias": "github-to-mockapi",
  "team_id": "tm_6PPg9VoEqV51I4ks9f4hzRdT",
  "disabled_at": null,
  "updated_at": "2021-06-17T20:19:06.550Z",
  "created_at": "2021-06-17T20:19:06.582Z",
  "filters": null,
  "destination": {
    "id": "des_0x7haWX4S9kQ5tAf3sHiprwA",
    "team_id": "tm_6PPg9VoEqV51I4ks9f4hzRdT",
    "label": "mockapi",
    "alias": "mockapi",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-06-17T20:19:06.566Z",
    "created_at": "2021-06-17T20:19:06.563Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false
  },
  "source": {
    "id": "src_G0NVftI704HYkseIslCctiyE",
    "team_id": "tm_6PPg9VoEqV51I4ks9f4hzRdT",
    "label": "github",
    "alias": "github",
    "disabled_at": null,
    "updated_at": "2021-06-17T20:19:06.560Z",
    "created_at": "2021-06-17T02:01:54.950Z",
    "integration_id": null,
    "url": "https://events.hookdeck.com/e/src_G0NVftI704HYkseIslCctiyE"
  },
  "ruleset": {
    "id": "rls_ITsLdTz80SoBUWW9a3GM6sw5",
    "alias": "default-ruleset",
    "team_id": "tm_6PPg9VoEqV51I4ks9f4hzRdT",
    "label": "Default Ruleset",
    "retry_count": 5,
    "retry_interval": 3600000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-05-07T21:19:35.607Z",
    "created_at": "2021-05-07T21:19:35.606Z",
    "alert_interval": 86400000,
    "alert_strategy": "last_attempt"
  }
}

We are going to omit the ruleset object for now; we are interested in the id and the url under source for the following steps.

Set Hookdeck URL in GitHub

We are going to add a webhook to our GitHub repository.

  1. Go in Settings of your repository.

Github repo settings

  1. Select the "Webhooks" tab.

webhook tabs

  1. Click Add webhook.

add webhook

  1. Paste the url in Payload URL.
  2. Select the content type application/json.
  3. Choose "Let me select individual events" and select the Branch or tag creation event.

webhook event selection

  1. Click Add webhook.

Great, we added a webhook that will send us an event every time a branch or tag is created.

Create a branch to trigger a webhook

We are now going to create a branch called API-Branch from "master" to trigger a webhook.

create api branch

Validate and inspect webhook in Hookdeck

After creating a branch, we want to query the API to validate if GitHub sent a webhook to our connection.

GET https://api.hookdeck.com/events?webhook_id=web_bKvPP9qnF16kNdR1XBMtK6aJ

Response:

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "evt_8d1ZvFEq6bSpp24j4mCvgI5j",
      "team_id": "tm_6PPg9VoEqV51I4ks9f4hzRdT",
      "webhook_id": "web_bKvPP9qnF16kNdR1XBMtK6aJ",
      "source_id": "src_G0NVftI704HYkseIslCctiyE",
      "destination_id": "des_0x7haWX4S9kQ5tAf3sHiprwA",
      "attempts": 1,
      "response_status": 200,
      "last_attempt_at": "2021-06-17T20:25:27.678Z",
      "next_attempt_at": null,
      "successful_at": "2021-06-17T20:25:27.822Z",
      "updated_at": "2021-06-17T20:25:27.839Z",
      "created_at": "2021-06-17T20:25:27.501Z",
      "status": "NONE",
      "event_request_id": "evtreq_ajmfCUF4h9kFV4EHeKoutTiZ",
      "cli_id": null
    }
  ]
}

We can see that we received an event associated with the connnection. Let's dig in deeper to inspect the event by using ther event's id. id: "evt_8d1ZvFEq6bSpp24j4mCvgI5j"

GET https://api.hookdeck.com/events/evt_8d1ZvFEq6bSpp24j4mCvgI5j

Response (trimmed down to show the relevant information):

{
  "id": "evt_8d1ZvFEq6bSpp24j4mCvgI5j",
  "request": {
    "body": {
      "ref": "refs/heads/API-Branch"
    }
  }
}

Something to note is we can also use the event id to inspect the webhook in the Hookdeck dashboard. We highly recommend it, as visualizing the webhook payload can be helpful for the testing and development workflow.

https://dashboard.hookdeck.com/events?selected_event_id=evt_8d1ZvFEq6bSpp24j4mCvgI5j

hookdeck github webhook success

Great, we can see in our API request and in Hookdeck's dashboard that the webhook event was indeed for creating our new branch called API-Branch.

Conclusion

Congratulations, we went through a simple example of setting up Hookdeck UI and the API to receive GitHub webhooks. You can now set up Hookdeck to receive any amount of webhooks without worrying about the infrastructure.