A Guide to Hookdeck Connections

Hookdeck Connections are the fundamental building block for routing events within the Hookdeck Event Gateway. Whether you're receiving webhooks from third-party services, sending webhooks to your users, building asynchronous APIs, or routing events between different platforms, Connections provide the powerful and flexible framework to manage how events are received, processed, and delivered. This guide will walk you through the components of a Connection and how to configure them to build robust, event-driven workflows for any use case.

Understanding Connections

What is a Connection?

At its core, a Connection is a pipeline that routes Events from a Source to a Destination . When Hookdeck receives an event at a Source's unique URL or via the Publish API, it sends a copy of that event through every Connection attached to that Source. This simple but powerful model allows you to create flexible routing patterns, including fanning out a single event to multiple Destinations.

Best Practices: Structuring Your Connections

How you structure your Connections can impact the clarity and maintainability of your event-driven architecture. There are two common approaches:

  1. Connection per Event Type: Each Connection routes a specific type of event to a dedicated endpoint. For example, a Shopify Order Created → Process Order Connection. This approach provides excellent visibility within Hookdeck, as each Connection maps directly to a specific business process.
  2. Connection per Service: A single Connection routes all events from a service (e.g., Shopify → My API). Your application is then responsible for inspecting the event payload and routing it to the correct internal logic. This reduces the number of Connections in Hookdeck but can make it harder to trace specific event flows from the dashboard.

For most use cases, we recommend starting with "Connection per event type" for its clarity.

Configuring the Components

A Connection is made up of three key parts: a Source, a Destination, and a set of rules that process Events as they pass through.

Sources - Where Events Originate

A Source represents a service that sends events to Hookdeck. Each Source is given a unique URL that you can provide to the sending platform (e.g., in your Stripe or Shopify webhook settings).

Using Source Types for Quick Setup

To streamline setup, Hookdeck offers Source Types for many popular platforms. When you select a Source Type like "Stripe," "Shopify," or "GitHub," Hookdeck automatically configures the Source to handle platform-specific requirements, such as signature verification. For any other service, you can use the "Generic Webhook" type.

Source Authentication

Hookdeck can verify the authenticity of incoming webhooks to ensure they are from the expected Source. For many Source Types, this verification is pre-configured. For others, you can manually set up authentication methods like HMAC, Basic Auth, or API Key verification. This ensures that only legitimate requests are processed.

Advanced Configuration

Sources offer advanced settings for fine-grained control:

  • Custom HTTP Methods: By default, Sources accept POST, PUT, PATCH, and DELETE requests. You can enable GET requests in the advanced settings if needed.
  • Custom Responses: Some webhook providers expect a specific response body or status code. You can configure a custom JSON, XML, or text response to meet these requirements.

Destinations - Where Events Are Sent

A Destination is the endpoint where Hookdeck sends your Events . Hookdeck supports several Destination types:

  • HTTP: A public URL for your API or server.
  • CLI: Your local development environment via the Hookdeck CLI.
  • Mock API: A built-in mock endpoint for testing and inspection without setting up your own server.

Controlling the Flow with Delivery Rate

To protect your Destination from traffic spikes, you can set a Delivery Rate. This limits how many Events Hookdeck sends per second, minute, or hour. You can also set a limit on the number of concurrent requests. Events that exceed the rate are safely queued and delivered as capacity becomes available.

Authentication with Your Destination

When Hookdeck forwards an event to your Destination, it can include authentication details to prove the request is coming from Hookdeck. You can configure various authentication methods, such as adding an API Key or Bearer Token to the request headers. By default, Hookdeck adds its own signature for verification.

Path Forwarding

If the original request to your Source URL includes a path (e.g., /my-path), Hookdeck will automatically append this path to your Destination URL. This is useful for routing events to different handlers on the same server. You can disable this behavior in the Destination settings if needed.

Connection Rules - Processing Events in Transit

Rules are powerful instructions that modify or control the flow of Events within a Connection .

Filtering Events

A Filter rule lets you conditionally route Events based on their payload. You can create filters that inspect the event's headers, body, query parameters, or path. This is perfect for routing Events based on their type.

For example, a filter on the body could look for {"type": "order.created"} to ensure only order creation Events pass through the Connection .

For more advanced filtering logic, see the Filters documentation.

Transforming Payloads

A Transformation rule allows you to modify the event payload using JavaScript before it reaches the Destination . This is useful for:

  • Adding, removing, or renaming keys in a JSON payload.
  • Standardizing different webhook formats into a single, consistent structure.
  • Converting data from one format to another (e.g., XML to JSON).

For example, you could add a static property like "source": "stripe" to every event body.

For detailed syntax and examples, refer to the Transformations documentation.

Delaying and Retrying Events

  • Delay: You can add a fixed delay to a Connection , holding an event for a specified time before sending it to the Destination .
  • Retry: Configure automatic retries for failed deliveries. You can set the strategy (linear or exponential backoff) and the number of retry attempts. This builds resilience into your webhook processing.

Conclusion

This guide has walked you through the core components of a Hookdeck Connection: the Source where events originate, the Destination where they are sent, and the Rules that process them in transit. You've learned how to configure each part to build a robust pipeline for your webhooks.

Now you're ready to put it all together. For a detailed guide on creating your first connection, see the Connections documentation.

Next -> Control Throughput and Queue Events to Prevent Spikes