Receive and Process Webhooks with Hookdeck

To reliably receive and process webhooks at scale, you need durable queueing, automatic retries, rate limiting, and full observability into every event. Hookdeck provides all of this as managed infrastructure — ingesting webhooks from any provider, queueing them durably, and delivering them to your services at a rate they can handle, with complete visibility into delivery status, failures, and performance.

If you're building an application that relies on inbound webhooks, Hookdeck replaces the custom ingestion pipeline you'd otherwise build and maintain. It handles the infrastructure complexity — retries, backpressure, monitoring, replay — so you can focus on your webhook processing logic.

Inbound webhook infrastructure

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.

Replay for Debugging and Recovery

When something goes wrong — a bug in your handler, a downstream service outage, or a deployment issue — you need to reprocess events. Hookdeck stores every event and allows you to replay them individually or in bulk:

  • Single event replay: Retry any event from the dashboard or API to reproduce and debug issues.
  • Bulk replay: Reprocess a range of events after fixing a bug or recovering from an outage. Use bulk retry to replay all failed events within a time window.
  • Safe replay with idempotency: When your handlers are idempotent, replay is always safe — you can reprocess events without risk of duplicate side effects.

Replay is one of the key advantages of managed webhook infrastructure over DIY solutions, where events are typically lost once processing fails.

Observability and Monitoring

Visibility into webhook delivery health is essential for catching issues before they affect your application. Hookdeck provides multiple layers of observability:

  • Metrics: Track delivery success rates, retry rates, latency percentiles, and throughput across all your sources and destinations. Export metrics to Datadog, Prometheus, or New Relic for unified monitoring.
  • Issues: Automatically detect and track delivery problems. Configure issue triggers to alert on exhausted retries, elevated error rates, or specific failure patterns via email, Slack, or webhook notifications.
  • Event logging: Every request, event, and delivery attempt is logged with full headers, payloads, and response data — searchable and filterable in the dashboard or via the API.

For a deeper dive into which metrics matter most, see Metrics.

Rate Limiting and Backpressure

Webhook bursts can overwhelm your services, especially during provider outages that trigger mass retries or high-traffic events like flash sales. Hookdeck protects your infrastructure with:

  • Max delivery rate: Set a maximum rate at which Hookdeck delivers events to each destination. Events exceeding the rate are queued and delivered as capacity becomes available.
  • Durable queueing: Events are durably stored while queued, so nothing is lost during traffic spikes. Hookdeck absorbs the burst and smooths delivery over time.
  • Connection pausing: Pause a connection during maintenance or incidents. Events continue to be ingested and queued, then delivered when you resume.

This means your application never needs to handle more traffic than it's configured for, regardless of how many webhooks arrive.

Debugging Failed Deliveries

When a webhook delivery fails, Hookdeck provides a systematic path to diagnosis:

  1. Check Issues: See which connections have active delivery problems and when they started.
  2. Inspect the event: View the full request payload, headers, and all delivery attempts with response data.
  3. Review attempt details: Each delivery attempt includes the HTTP status code, response body, response time, and any error details from your destination.
  4. Identify the pattern: Use Metrics to see if failures are isolated or systemic — is it one event or a spike across all events?
  5. Fix and replay: Once the issue is resolved, retry failed events individually or in bulk to recover.

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.

Control Throughput and Queue Events to Prevent Spikes ->

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

Hookdeck can be integrated within your CI and CD workflow using the Hookdeck API, SDKs, Terraform provider, or the Hookdeck CLI v1.2.0+.

CLI Integration Example

The CLI's upsert command enables safe, idempotent deployments:

# GitHub Actions example
- name: Update Webhook Configuration
  run: |
    hookdeck connection upsert production \
      --source-name stripe \
      --destination-url ${{ vars.API_URL }}/webhooks

This approach ensures consistency across environments and prevents misconfiguration. Use --dry-run locally to preview changes before committing to your repository.

Manage Connections with the Hookdeck CLI ->

Learn how to manage webhook connections programmatically using the Hookdeck CLI for Infrastructure as Code, CI/CD integration, and production workflows.

Frequently Asked Questions

How do I receive webhooks reliably at scale?

Use managed webhook infrastructure like Hookdeck to ingest, queue, and deliver webhooks with automatic retries, rate limiting, and observability. This replaces the custom queueing, retry logic, and monitoring you'd otherwise need to build. See the quickstart to get started.

What happens if my server is down when a webhook arrives?

Hookdeck durably queues all incoming webhooks. If your destination is unreachable, events are held in the queue and delivered when your server recovers. Combined with automatic retries, this ensures no events are lost during outages or deployments.

How do I handle duplicate webhook deliveries?

Hookdeck provides at-least-once delivery, meaning events may be delivered more than once. Implement idempotent webhook processing using a unique event identifier (such as the x-hookdeck-eventid header) to ensure duplicate deliveries don't cause duplicate side effects.

How do I debug failed webhook deliveries?

Use Hookdeck's Issues to identify failing connections, then inspect individual events to see the full request/response data for each delivery attempt. Metrics help identify whether failures are isolated or systemic. Once fixed, replay failed events to recover.

Can I receive webhooks from multiple providers through Hookdeck?

Yes. Create a separate Source for each webhook provider (e.g., Stripe, Shopify, GitHub) and configure Connections to route events to the appropriate destinations. Each source gets its own webhook URL to register with the provider.

Next -> Quickstart