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 webhook events.

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 supports sending webhooks 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 of type Hookdeck Publish API in Hookdeck to represent that account using the Sources API endpoint. The Hookdeck Publish API type ensures indicates the Publish API must be used to publish webhook events. The Source name should use a unique identifier that you can use to map it back to the account in your system.

The Hookdeck Sources API endpoint will return source_id and source_url properties when you create a Source. You can use either of these to publish webhook events for that account, though using the unique name you provided is typically the simplest and most maintainable approach.

Whenever an event occurs in your system that needs to be sent as a webhook, you'll need to make an HTTP request to the Hookdeck Publish API with a Source identifier and the request headers and body that you want the webhook to contain. The request can be in any content type supported by Hookdeck. The Publish API is authenticated using your Hookdeck Project API key.

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

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 with rules. 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. Source or Destination already exists, the API will return the existing resource. To achieve idempotency of existing connection, ensure you pass the unique name.

PUT /connections

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

Implementing "Topics" (or "Event Types")

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 webhook events

Now that it's time to send webhooks, you only need to send an HTTP POST request to the Hookdeck Publish API 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.

POST https://hkdk.events/v1/publish

Content-Type: application/json
Authorization: Bearer $API_KEY
X-Hookdeck-Source-Name: account-123

{
  "event_type": "order_created",
  "order_id": "1234567890"
}

For more information, see the Publish API documentation.

Displaying webhook history & configured webhooks to your users

The connections and events API endpoints can be filtered by source_id (If you only store the Source name you will need to find the Source by name).

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