Send Webhooks With Hookdeck

If you're building a developer platform or a SaaS product, your customers may want to be programmatically notified when events occur in your platform. Learn how to use the Hookdeck event gateway to securely and reliably send outbound webhooks.

Outbound webhook infrastructure

Skip to the Quickstart ->

Read the quickstart guide for a practical example on how to get started.

Webhooks are the most ubiquitous notification mechanism, involving outbound HTTP requests to URLs provided by your customers. Hookdeck offers infrastructure and functionality that enables you to configure and reliably send webhooks to your customers.

Through the Hookdeck API, you can expose the following functionality to your customers:

  • Register webhook URLs
  • Filter events by payload and header
  • Transform event payloads and headers
  • Set configurable retry policies
  • Provide flexible authentication mechanisms
  • Display registered webhooks
  • Display webhook history and delivery status

How to use Hookdeck for outbound webhooks

This guide provides a common approach to using Hookdeck for outbound webhooks. It assumes that you will provide a UI for registering webhook URLs within your platform's dashboard and that your platform has the concept of an account (tenant).

This guide covers a core subset of potential functionality:

  1. How to map Hookdeck Connections, Sources, and Destinations to your platform's accounts
  2. Signing webhooks
  3. Sending webhooks
  4. Retrieving registered webhooks
  5. Displaying webhook history and delivery status
  6. Error handling and recovery
  7. Alerting and monitoring

Understanding Sources, Destinations, and Connections

Hookdeck handles webhooks by connecting Sources and Destinations in a many-to-many relationship. A Connection consists of a Source, a Destination, and a set of optional rules. It defines the flow of the Event , from receipt through to delivery.

The term "account" is used in the context of this guide to represent the entity that owns the webhook in your system. You can replace it with terms such as "team", "project", "tenant", "workspace", "user", etc. that best fit your application.

In this context, Sources represent the accounts in your system that send webhooks, and Destinations represent the webhook URLs that your accounts provide.

Create a source per account

When a new account is created in your system, create a Source in Hookdeck to represent that account. The Source name should use a unique identifier that you can use to map it back to the account in your system.

The Hookdeck API will return source_id and source_url properties that you can use to publish webhooks for that account.

Whenever an event occurs in your system that needs to be sent as a webhook, you'll need to make an HTTP request to that source_url with the request headers and body that you want the webhook to contain. The request can be in any content type supported by Hookdeck.

Since Sources are not authenticated by default, you can enable API Key authentication to secure the endpoint by providing your own API Key.

There is no limit on the number of Sources in your workspace.

Note: We're testing a new Publish API that uses your Hookdeck API Key to authenticate the request and allows you to publish using the source name. Contact us if you want to try it out.

Connect a Destination for each account endpoint URL

When an account wants to register a new webhook URL in your system, create a new Connection using the associated account Source ID. The connection will require a Destination and a Ruleset. The Destination represents your user's webhook URL endpoint they wish to register. Hookdeck will forward all webhooks from the Source to all associated Destinations.

There is no limit on the number of Destinations or Connections in your workspace.

API Idempotency

Hookdeck APIs are idempotent by design and can create all necessary resources within the same API call. This means that you can create a Source, Destination, and Connection in a single API call without creating a new source for each new connection. If the Source or Destination already exists, the API will return the existing resource.

PUT /connections

{
  "name": "account-123-endpoint-123",
  "source": {
    "name": "account-123",
  },
  "destination": {
    "name": "endpoint-123"
    "url": "https://myapp.com/webhook"
  }
}

Implementing "Topics"

Popular webhook implementations support different topics that the account wants to receive. Topics can be implemented as Filter Rules on the connection. Hookdeck rules are much more flexible than topics, but it's up to you if you want to allow your accounts to use our full filter syntax or implement pre-configured rules.

Signing the payload

An important part of webhook security is the payload signature, which is generally implemented as an SHA-256 hash of the request body along with a unique secret for the account.

Destinations use the "Hookdeck Signature" authentication strategy by default. Since that Signature uses your project secret, you can't use it to send webhooks to a 3rd party. Instead, you can use a "Custom Signature" strategy where you can provide a unique secret for each account. That secret can then be shared with the account owner and used to verify the signature. Our custom signatures are a simple HMAC-SHA256 hash of the request body and the secret, base64 encoded.

Using your own signatures

While Hookdeck offers the ability to sign payloads, for backward compatibility reasons or other requirements, you may want to use your own algorithm. Since Hookdeck doesn't alter the payload or headers of the published webhook, you can sign the payload using your own algorithm when sending the HTTP request to your Source URL.

White-labeling Hookdeck headers

Hookdeck adds x-hookdeck prefixed headers to the request that can be used to identify the request. Some of those headers are not necessary for your users and can be removed. The x-hookdeck prefixed headers can be replaced with your own prefix in your Project settings. See Use custom HTTP headers prefix.

Sending webhooks

Now that it's time to send webhooks, you only need to send an HTTP post request to the associated account Source URL along with the request data. You should note that we enforce a 1MB limit on the payload size. If the request was successful Hookdeck will return an HTTP 200 with the associated event_request_id in Hookdeck. Any ingestion errors will specify the cause and resolution step.

Displaying webhook history & configured webhooks to your users

The connections and events API endpoints can be filtered by source_id. By using the associated account Source ID as the filter, you will be able to display only the resources that belong to them. You can build your own UI to register new endpoints, browse events, retry events, and perform other actions that are available within Hookdeck. All of our functionalities are available programmatically via the API.

Next -> Quickstart