Customize Outgoing Webhook Headers

When Hookdeck processes and delivers your webhooks, it adds several informational headers. While these headers are useful for debugging and tracking, you might want to customize their prefix for branding purposes or to simplify the experience for your webhook consumers. This guide explains how to use Hookdeck's header white-labeling feature to achieve this.

Why Customize Outgoing Webhook Headers?

Customizing the prefix of headers added by Hookdeck offers several benefits:

• Branding (White-Labeling): Present webhooks to your users as originating more directly from your platform. Instead of seeing x-hookdeck- headers, they'll see headers prefixed with your chosen brand identifier (e.g., x-yourapp-).
• Reduced User Confusion: If your users are not directly interacting with or aware of Hookdeck as an intermediary, the default x-hookdeck- prefixed headers might be confusing or irrelevant to them. A custom prefix makes the headers' origin clearer in the context of your application.

Hookdeck typically adds headers like x-hookdeck-event-id, x-hookdeck-attempt-id, and x-hookdeck-signature to outgoing webhooks. The white-labeling feature allows you to change the x-hookdeck- part of these headers.

Hookdeck's Header White-Labeling Feature

Hookdeck provides a straightforward way to customize these header prefixes at the Project level.

• Project-Level Configuration: This feature is configured within your Hookdeck Project settings. The change will apply to all webhooks sent from that Project.
• Custom Prefix: You can replace the default x-hookdeck- prefix with a custom string that aligns with your branding (e.g., x-yourapi-, x-mycompany-).

Example:

If you set your custom prefix to x-yourapp-:

• Default header: x-hookdeck-event-id

• Becomes: x-yourapp-event-id

• Default header: x-hookdeck-signature

• Becomes: x-yourapp-signature

How to Configure a Custom Header Prefix

Follow these steps to set up a custom header prefix in your Hookdeck dashboard:

1. Navigate to Project Settings:

   • Log in to your Hookdeck dashboard.
   • Select the Project for which you want to customize headers.
   • Go to the Settings tab for that Project.

2. Locate and Enable Custom Prefix:

   • Scroll to find the section related to HTTP headers or advanced settings.
   • Look for the option labeled "Use custom HTTP headers prefix".
   • Enable this feature using the toggle.

3. Enter Your Desired Prefix:

   • A text field will appear, allowing you to input your custom prefix.

   • Ensure your prefix is in the format x-yourprefix-. It typically needs to start with x- and end with a hyphen -.

4. Save Changes:

   • Click the "Save" button to apply your new custom header prefix.

Once saved, Hookdeck will immediately start using your custom prefix for the relevant headers on all new outgoing webhook Attempts for that Project.

Which Headers Are Affected?

When you enable a custom header prefix, it applies to the informational headers that Hookdeck adds during webhook processing and delivery. The key headers affected include:

• x-hookdeck-event-id → x-yourprefix-event-id
• x-hookdeck-attempt-id → x-yourprefix-attempt-id
• x-hookdeck-signature → x-yourprefix-signature (This is crucial if Hookdeck is signing the webhooks for you and your consumers verify this signature)
• x-hookdeck-source-id → x-yourprefix-source-id
• x-hookdeck-destination-id → x-yourprefix-destination-id
• x-hookdeck-verified-signature → x-yourprefix-verified-signature (Indicates if an incoming signature was verified by Hookdeck)

Important Considerations

Keep the following points in mind when using the custom header prefix feature:

• Informing Your Users: If your webhook consumers rely on these headers (especially the signature header for verification), you must update your developer documentation to reflect the new custom prefix. Failure to do so can break their integration. Clearly communicate the new header names they should expect.

• Project-Wide Consistency: The custom prefix applies to all webhooks sent by Hookdeck from the Project where it's configured. It's not possible to set different prefixes for different Connections or Destinations within the same Project.

• Unaffected Headers: This feature only affects the prefix of headers added by Hookdeck itself.

  • Any headers you include when initially publishing an Event to Hookdeck (e.g., via the Publish API) are passed through to the Destination as-is, without prefix modification.
  • Headers added by the original Source (if Hookdeck is receiving from a third-party service) are also generally passed through, though some might be used by Hookdeck for its processing (like an incoming signature for verification).

Related Documentation

For more detailed information on related features and concepts, refer to the following Hookdeck documentation:

Project Settings: Custom HTTP Headers Prefix ->

Detailed guide on configuring project-level settings, including the custom header prefix.

Destination Headers ->

Learn about headers Hookdeck adds when delivering to your destinations.