Receive and Process Webhooks with Hookdeck

If you're building an application that relies on inbound webhooks, you need to be able to reliably process, monitor and troubleshoot them. Hookdeck provides a scalable solution for receiving, queuing, and processing webhooks.

Skip to the Quickstart ->

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

This guide provides an overview of how to use Hookdeck for inbound webhooks. It assumes that you are receiving webhooks from a third-party provider such as Shopify, Github, Stripe, Twilio, etc., and that your own application will process those webhooks.

This guide covers a core subset of potential functionality:

1. Configuring your Connections, Sources and Destinations
2. Setting up rules to retry, filter and route events
3. Receiving webhooks, handshaking and verification
4. Testing your application on a local server
5. Error handling, alerting and monitoring
6. Best practices

Understanding Sources, Destinations, and Connections

Hookdeck acts as an HTTP proxy and queue between the webhook producer and your application. To receive and process webhooks, you need to define a Source , a Destination and configure a Connection between them.

Sources as webhook producers

A Source represents a service that sends webhooks to Hookdeck. For each Source, you will be provided with a unique Webhook URL that you can use to send webhooks to Hookdeck. Typically, sources are named after the service that sends the webhooks, such as shopify or stripe.

Most providers will allow you to configure a set of event types or topics you want to receive. Using a single source for all types will allow you to fully manage the delivery of events to your application within Hookdeck and only provide a single URL to your webhook producer.

Tip: Use one source per webhook provider and re-use it across your connections.

Destinations as event consumers

A Destination is the HTTP URL to which Hookdeck delivers the events. Typically, the Destination is the HTTP URL you previously used to receive webhooks.

You can have a single Destination to represent your entire API, such as https://api.example.com/webhooks/shopify, or you can use a different Destination per event, such as https://api.example.com/webhooks/order-created. Using a Destination per event improves observability and allows you to manage the delivery rate of each event separately, while the opposite lets you manage the delivery rate of all webhooks.

The more granular your Destinations, the more granular the Event metrics and logs will be.

Connections for flow control

A Connection consists of a Source, a Destination and set of optional rules. It defines the flow of the Event , from requests through to delivery. When a webhook Request is received, Hookdeck will create a new Event for each eligible Connection. You can visit the Events page of your dashboard to inspect the events and their delivery status.

Rules allow you to configure the behaviour of Events received on the Connection.

Retries

The retries rule lets you configure automatic retries for Events that do not receive a 2XX status code response from your Destination. You can also configure the number of automatic retries and the time interval between each Attempt . You can retry for up to a week and 50 delivery Attempts. Each delivery Attempt is logged, and your Destination response data can be used to determine the cause of the failure.

Fanning-out events to multiple destinations

Hookdeck will create and deliver a copy of the Event for each eligible Connection. This allows you to simultaneously send the same or a transformed Event to multiple Destinations. For example, that same Event could be sent to 2 different services, such as your API and an S3 bucket for backup.

Filtering events

Webhook producers are often "noisy" and may send many webhooks you don't need. You can use a filter rule to deliver Events matching specific criteria to a Destination. You can define a filter to only deliver Events with a specific type or topic to a specific Destination or configure more complex filters based on any Event data.

Filters can be used in conjunction with multiple Destinations to route Events to different endpoints based on their content.

Receiving webhooks

Webhooks are received on your Source URL. Any HTTP request received will be represented by a new Request within Hookdeck. You can visit the Requests section of the dashboard to see your requests.

To receive webhooks, you must register that URL to your webhook provider.

Each provider has its own way of registering webhooks. With some providers, the webhook URL must be registered through their dashboard, while others will require you to use their API.

Challenges and handshake

Some providers require you to verify your endpoint before webhooks are delivered. For example, Facebook will send a "challenge" request that requires a specific response to be valid. Hookdeck automatically detects and completes the challenge (also known as "handshake") for you without any additional configuration.

If you encounter a provider with a challenge we do not support, contact us. We'll add support for it within 24 hours.

Built-in platform handshakes and challenges ->

Developing and testing on a local server

When developing your application, you can use the Hookdeck CLI to receive Events on a local server or private network. This allows you to receive webhooks on your local machine without deploying your application to a public server with an HTTP URL.

Monitoring and error recovery

Hookdeck keeps logs of all Requests, Events, and delivery Attempts, which you can view in the dashboard or query via the API. Failed Events can be retried automatically, manually, or in bulk.

Leveraging issues for problem resolution

Issues serve as an alternative approach to dead-letter queues (DLQ), allowing you to track and resolve problems that occur within your application. You can set Issue Triggers to open issues when certain criteria are met. For example, you can set an Issue Trigger to alert you when event has exhausted its automatic retries or as soon as an event fails to be delivered.

Issues can be used to track and resolve those problems. You'll be notified via email, Slack, or another supported notification channel when an issue opens.

Using metrics to monitor usage and performance

Metrics provide insight into your Requests, Events, and Attempts. They are available in the dashboard and can be exported to your observability platform, such as Datadog. Metrics include important insights for troubleshooting your server response latency, delivery rates per destination, error rates, and more.

Best Practices

Process events synchronously

Hookdeck acts as your queue, allowing you to process events synchronously when received from Hookdeck. It provides a 60-second default timeout window for you to process each Event and return a response.

Implementing another event queue when receiving events from Hookdeck is redundant as it already behaves as a push queue. To control the rate your server processes requests, simply set a rate limit on your Destination.

How to Control Throughput and Queue Events to Your Destination ->

Learn how to prevent spikes and control throughput

Process events out-of-order

There's no guarantee of the order in which Events will arrive. Your application should use its own logic to order events upon receiving them. Always use relevant data from the event payload, such as an updated_at value, to ensure you don't process stale requests that might overwrite more recent updates.

Hookdeck delivers Events in the order they arrive on a best effort basis but there's no guarantee Hookdeck receives them in order.

Process events idempotently

Hookdeck operates on an "at least once" delivery guarantee, meaning an Event may be delivered more than once. Ensure that your event processing logic is idempotent, meaning that processing the same event multiple times does not lead to unintended side effects.

For operations that are not inherently idempotent, you can track a unique identifier in the events, such as the x-hookdeck-eventid header, to ensure the operation is only performed once.

Verify your events

Since webhook URLs are public, unauthenticated endpoints, verifying that the events are coming from a legitimate source is important to ensure an imposter isn't forging requests. Hookdeck supports webhook signature verification and will resign each request.

Since Hookdeck doesn't change the body or headers of the requests, you can either verify the original provider's signature in your application or configure Source verification for all your Sources and only verify the Hookdeck signature.

For signatures that include a timestamp, Hookdeck retries beyond the validation window of that timestamp will cause verification failure. Timestamp checks are optional and be disabled to be compatible with Hookdeck. If your endpoint is idempotent, it's sufficient to prevent replay attacks, and timestamp checks are unnecessary.

Implement signature verification ->

Integrate with your CI/CD

Using the Hookdeck API, SDKs, or Terraform provider, Hookdeck can be integrated within your CI and CD workflow. We recommend creating connections and registering all webhooks programmatically to avoid data loss due to misconfiguration and ensure consistency across environments.