Add support for custom headers (e.g., X‑Api‑Key) on webhook destinations

[victorperez2911]

Hello team,

I'm currently using Outpost to handle outbound webhooks for one of my projects. The workflow is straightforward: I register destinations of type webhook and then use the Outpost API to publish events. Outpost reliably delivers these events to the URLs configured for each destination. Thank you for providing this open‑source solution!

However, I have a use case that requires Outpost to include a custom header on each outbound webhook request. Specifically, the receiving service expects a static X‑Api‑Key header with a secret value. After reviewing the documentation and source code, it appears that Outpost cannot currently add arbitrary headers to webhook requests:

The configuration reference lists environment variables for webhook destinations. We can disable the default headers (X‑Outpost‑Event‑Id, X‑Outpost‑Signature, etc.) and change their prefix using DESTINATIONS_WEBHOOK_HEADER_PREFIX, but there is no option to define custom headers like X‑Api‑Key
outpost.hookdeck.com
.

The destwebhook provider code constructs the HTTP request and iterates over Outpost metadata, adding only the predefined headers with the configured prefix
raw.githubusercontent.com
. There is no mechanism to append user‑defined headers or include API keys.

Given the growing need to forward events to APIs that require API keys or other custom authentication headers, would it be possible to add this capability to Outpost? A few ideas that might satisfy this requirement:

Allow specifying a static header key/value pair (e.g., x-api-key=secretValue) in the destination configuration or environment variables.

Add a custom_headers map in the Destination model so that any key/value pairs are included in the HTTP headers when sending the event.

Alternatively, document an officially supported pattern (such as a built‑in proxy option) to inject custom headers before forwarding the request.

I appreciate any guidance on whether this feature is planned or if there is a recommended workaround. I’m willing to contribute or test a solution if needed. Thanks again for the great work on Outpost!

[alexbouchardd]

Hey @victorperez2911,

The way Outpost handles this is through the metadata properties when publishing an event. The metadata is mapped to HTTP headers for webhook destinations.

{
  "tenant_id": "12345",
  "time": "2024-06-01 08:23:36.082374Z",
  "metadata": {
    "Api-Key": "api_key_123456"
  },
  "data": {
    "hello": "world"
  }
}

If you've set the DESTINATIONS_WEBHOOK_HEADER_PREFIX to X- then with the above payload the request will include a header X-Api-Key

Does that make sense?

[alexbouchardd]

I think that's a great idea given the header example here is a static value

Add a custom_headers map in the Destination model so that any key/value pairs are included in the HTTP headers when sending the event.

[victorperez2911]

Hey @victorperez2911,

The way Outpost handles this is through the metadata properties when publishing an event. The metadata is mapped to HTTP headers for webhook destinations.

{
  "tenant_id": "12345",
  "time": "2024-06-01 08:23:36.082374Z",
  "metadata": {
    "Api-Key": "api_key_123456"
  },
  "data": {
    "hello": "world"
  }
}

If you've set the DESTINATIONS_WEBHOOK_HEADER_PREFIX to X- then with the above payload the request will include a header X-Api-Key

Does that make sense?

Tks, This has helped me for now.