Hookdeck Basics

---

Hookdeck is managed webhook infrastructure that receives, routes, transforms, and delivers webhook events with full observability from development through production. It replaces the custom queues, retry logic, and monitoring you'd otherwise build and maintain yourself — so your team can focus on building product, not maintaining plumbing.

When to Use Hookdeck

Hookdeck is the right fit when you need to:

• Receive webhooks from third-party providers like Stripe, Shopify, GitHub, or Twilio and process them reliably without building your own ingestion layer. See Receive Webhooks.
• Retry and replay failed events automatically with configurable backoff strategies, or manually replay events for debugging and recovery. See Retries.
• Monitor webhook delivery health with delivery metrics, latency tracking, error rates, and alerting — exported to your existing observability stack. See Metrics.
• Scale webhook processing without overwhelming your services, using rate limiting, backpressure, and durable queueing.
• Route events across multiple services by fanning out a single webhook to multiple destinations with filtering and transformation.

What Problems Hookdeck Solves

Most developers underestimate webhook complexity until something breaks in production. Hookdeck addresses the most common pain points:

• Missed webhook events: Without durable queueing, a server restart or deployment can silently drop events. Hookdeck queues every event and guarantees at-least-once delivery.
• No visibility into failures: Debugging webhook issues without logs or metrics is guesswork. Hookdeck provides full request/response logging, delivery metrics, and issue tracking.
• Retry logic complexity: Building robust retry with exponential backoff, dead-letter handling, and manual replay is significant engineering work. Hookdeck handles this out of the box with configurable retry policies.
• Scaling bottlenecks: Webhook bursts can overwhelm your application. Hookdeck absorbs traffic spikes with durable queueing and delivers events at a rate your services can handle.
• Development friction: Testing webhooks locally requires tunnels and workarounds. The Hookdeck CLI brings production-like webhook delivery to your localhost.

Concepts

This section covers the fundamental concepts you should understand within Hookdeck.

Sources

A source represents any service that makes an HTTP request to the URL for a source defined within Hookdeck. The HTTP requests can be inbound events such as webhooks or effectively API calls to trigger a workflow defined by a connection. Hookdeck is designed to be compatible with various content types and API providers, and supports a variety of authentication mechanisms (see authentication). Some providers require a handshake or challenge for validation, and Hookdeck supports this for several platforms.

For more information, see Sources.

Destinations

Represents the destination for an event to be routed to. A destination can be connected to one or many Sources.

For more information, see Destinations.

Connections

Connections in Hookdeck route an Event from a Source to a Destination, optionally including additional logic through connection Rules. Connections can reuse sources and destinations, allowing one event to be routed to multiple destinations.

For more information, see Connections.

Event lifecycle

The following represent different stages of the lifecycle of an event within Hookdeck:

• Requests: An HTTP request received by a Source URL defined within Hookdeck, such as a webhook.
• Events: Once a request is associated with a connection, it becomes an event. Events move through the connection's rules pipeline (filters, transformations, deduplication) in a configurable order. Events can be ignored at various stages if they don't pass a filter, fail transformation, or are identified as duplicates. Only events that successfully pass all connection rules are queued for delivery to the destination.
• Attempts: An HTTP delivery attempt to the URL defined by a Destination.

For more information, see Events and Attempts, Connection Rules, and Filters.

Features

Hookdeck features at a glance:

• Bookmarks: Store and replay common and edge case requests.
• Transformations: Transformations modify the data payload of events in transit, allowing seamless service connections by changing the data structure of the source to match the expected structure of the destination.
• Filters: Filters define rules for processing events based on payload structure and content, headers, paths, and rejecting the rest.
• Delivery rates: Define a maximum rate at which Hookdeck will make requests to a destination
• Retries: A repetition of a previously attempted delivery. Retries can be triggered manually on any event, or automatically on failed events based on defined configuration.
• Issues & Notifications: Get notified of event delivery issues, track problems in your project and communicate resolution steps with your team.

Use cases

Common use cases for the Hookdeck Event Gateway are as follows:

Inbound webhook infrastructure

Use Hookdeck as infrastructure to receive, process, and deliver webhooks to your services.

For this use case, Hookdeck takes the load off of your infrastructure by ingesting webhooks at any scale, processing them with features such as transformations to change payloads, and filtering to route or exclude events. Hookdeck also manages the delivery of webhooks to one to more destinations with a max delivery rate and automatic retry configuration that you define.

Try the Receive Webhooks quickstart to get started.

Outbound webhook infrastructure

Reliably deliver webhook events to user and customer endpoints.

Set up Connections that define the route to your customer's endpoint, making use of Filters for fine-grained routing, along with delivery rate and automatic retries for an improved webhook ingestion experience for your customers. Additionally, use issues and notifications to keep track of problems with customer endpoints.

Try the Send Webhooks quickstart to get started.

Third-party to third-party message routing

Connect APIs and other third-party services with the Hookdeck Event Gateway.

Use Transformations to adjust event payload structure and HTTP headers, and filters to route messages between services. Use a delivery rate to adhere to any third-party API rate limiting requirements and configure automatic retries to ensure that messages are successfully delivered. Additionally, issues and notifications can help you keep track of any problems with the APIs and services that you're using within your event-driven applications.

Try the Third-Party Routing quickstart to get started.

Asynchronous API Gateway infrastructure

Reliably consume asynchronous API requests at scale using Hookdeck as your Asynchronous API gateway infrastructure.

Use Hookdeck to authenticate and queue API requests to your infrastructure using rate limiting to throttle inbound requests. Pause API requests during planned or unexpected downtime, safe in the knowledge that API requests are queued to be delivered later and bulk retry events as part of your error recovery strategy.

Try the Asynchronous API Gateway quickstart to get started.

Serverless message broker

Hookdeck is your serverless infrastructure for asynchronous messaging between your serverless applications and services.

Define Connections between the components in your event-driven architecture and use features such as Filters to intelligently route messages, and Transformations to conform payloads. Hookdeck reliably queues and delivers events to and between your serverless functions thanks to rate-limiting and automatic retries.

Data Retention

The amount of time that Hookdeck retains your event data depends on your plan. To check your plan, visit the Billing section in the Hookdeck dashboard.

Once your data retention period has passed, any Request, Event, or Attempt data older than the retention period will no longer be accessible in the dashboard or via the API. However, we do retain the data for the maximum data retention period of the highest plan to allow you to upgrade and access the data. Additionally, any queued Events will be removed from the queue and will not be delivered.

Frequently Asked Questions

What is Hookdeck?

Hookdeck is managed webhook infrastructure for engineering teams. It provides durable queueing, automatic retries, rate limiting, filtering, transformations, and full observability for inbound and outbound webhook events. Rather than building and maintaining your own webhook processing pipeline, Hookdeck handles the infrastructure so you can focus on your application logic.

How does Hookdeck handle failed webhook deliveries?

When a delivery attempt fails (non-2XX response or timeout), Hookdeck automatically retries based on your retry configuration. You can define the retry strategy (linear or exponential backoff), the number of attempts, and the time window. If all retries are exhausted, Issues alert your team so you can investigate and manually retry. Every delivery attempt is logged with full request/response data for debugging.

Does Hookdeck guarantee webhook delivery?

Hookdeck provides an at-least-once delivery guarantee, meaning every event will be delivered at least once to your destination. This means your webhook handlers should be idempotent to safely handle potential duplicate deliveries. For more on delivery semantics, see Webhook Delivery Guarantees.

Can Hookdeck return the response from a destination to the source?

Hookdeck is a platform for asynchronous messaging and therefore returns a basic customizable synchronous HTTP response to the client that has invoked the source URL. It is not possible to synchronously return a response from a destination to the client (for example, the result of an API call).

However, there are two options for your to receive the response from the destination event delivery using an asynchronous workflow:

1. Configure an event.successful webhook notification which will contain the payload of the response from a successful request to a destination URL. See configuration webhook notifications.
2. Send the result of any work done by a destination via a webhook callback. See the send a webhook quickstart for an example.

Does Hookdeck support debouncing events?

No. At present we do not support debouncing.

Does Hookdeck support multipart/form-data requests with attachments?

Multipart/form-data requests are supported. However, attachments are not supported and the attachment data will become malformed.

If you have a use case for for anything in the FAQ, please let us know in our Slack community or send us a message.