Support fully customizable webhook signature header name (not just prefix)

[ambroziepaval]

Is your feature request related to a problem? Please describe.
We're planning to migrate our webhook infrastructure to Outpost. We already have thousands of integrated clients receiving webhooks from us today, and our existing contract with them specifies a fixed signature header name that does not use the -signature suffix. For example, something like x-acme-digest.

Today, DESTINATIONS_WEBHOOK_HEADER_PREFIX lets us customize the header prefix (e.g. x-acme-), but the suffix signature is hardcoded, so we can only ever produce x-acme-signature.

Because we already have an established contract with our clients, we can't ask them all to change the header they read. To make the migration to Outpost as seamless as possible (ideally zero client-side changes), we need to emit the signature under our existing header name.

Describe the solution you'd like
Make the signature header name fully customizable, not just the prefix. Something like:

A new field on DestinationWebhookConfig, e.g. DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME.
When set, this value is used as the complete signature header name, bypassing the <prefix>signature construction entirely. When unset, behavior is unchanged (defaults to signature), so this is fully backwards compatible.
Example: with DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME=x-acme-digest, the delivered header would be exactly x-acme-digest regardless of the configured prefix.
The key point is control over the entire header name. The prefix option only covers part of the naming; consumers with an existing, fixed header contract need to pin the full name.

This mirrors the existing precedent where the signature value is already customizable via DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE: we'd simply be extending that same "make signatures interoperable with existing consumers" philosophy to the header name.

I'm happy to implement this and open a PR. I've traced the two call sites above and reviewed the config-field workflow in contributing/config.md (struct field + tags, defaults, LogConfigurationSummary(), validation, go generate for docs). I just wanted to align on the approach and naming before writing the code.

Describe alternatives you've considered

• Custom headers: We can add arbitrary static headers per destination, but those carry static values. They can't carry the computed per-request signature, so this doesn't solve our case.
• Header prefix only (DESTINATIONS_WEBHOOK_HEADER_PREFIX): Adjusting the prefix still leaves the mandatory signature suffix, producing x-acme-signature rather than x-acme-digest.
• Post-processing/proxy layer to rename the header in flight: Adds operational complexity and an extra hop purely to rename one header; this is not viable at our scale.
• Asking clients to update the header they validate: Not really feasible with thousands of existing integrations under contract.

Additional context

• We'd want this to work in both default and standard webhook modes, since the suffix is hardcoded in both providers.
• Backwards compatibility: unset config can preserve today's exact behavior.

[alexluong]

Hi @ambroziepaval, glad to hear you're exploring using Outpost for your webhook infrastructure. We definitely aim to design Outpost so that you can achieve full backward compatibility with your existing pattern.

Can you share the webhook headers or any relevant documentation so we can understand your use case better?

Is this something you're interested in contributing?

Regardless, I'll keep an eye out and will let you know what we can do here!

[ambroziepaval]

Hi @alexluong , thanks for the quick and open response!

We are building a centralised webhooks service to replace several existing live webhooks systems, so we need to preserve backward compatibility with the header contracts our current clients depend on. Rather than sharing our full public docs (they only cover part of the picture), here's the concrete shape of what we need:

• the bulk of our public API verify against a x-flywire-digest header: i.e. the signature under a header name with no -signature suffix.
• a subset of clients expect a message-signature header instead
• a further subset expect a cusom header carrying an API-key value OR basic auth: this last group we can cover today with the existing custom_headers, with the caveat that this stores the value in plain text (whereas the signing secret in credentials is encrypted at rest). Is there a recommended way to store a sensitive static header value encrypted-at-rest?

What would be ideal for us
A configurable signature header, as a global default (e.g. DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME) that can be overridden at the tenant/destination level. Gloval covers our dominant contract in one setting, the per-destination override lets us map the minority (they can later migrate to the global one on their on timeline)

And yes, this is something I'm interested in contributing.
I have some other ideas for enhancements, but I'll add those as separate issues to not diverge too much from this topic.

[alexluong]

Hi @ambroziepaval, thanks for the context! And glad to hear you're interested in contributing. Let's discuss this issue in more details to make sure we're on the same page before figuring out the PR/implementation.

So I see 2 things that need evaluation with this issue.

1: Adding new config DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME. I don't love adding new config, especially for this since we may need to do the same for the other headers for consistency purposes. So we may need to add DESTINATIONS_WEBHOOK_TIMESTAMP_HEADER_NAME, DESTINATIONS_WEBHOOK_EVENT_ID_HEADER_NAME, etc., which is not ideal.
2: I'm also not sure about how to support this requirement "a subset of clients expect a message-signature header instead" just yet.

Some questions for you.

• Are you open to changing the headers schema long-term or is your design something we want to keep?
• Do you plan to use the portal? Or are you building your own portal? Or is there no user-facing portal to manage destinations & events?

What I'm thinking is if we can do something with destination.delivery_metadata feature where we can support {{.Signature}} or some version of that.

The message-signature header is difficult because it affects the ability to set prefix. So we can either skip prefix altogether and have to manually include x-flywire- everywhere, or we need to do something else with that header.

---

We'd want this to work in both default and standard webhook modes, since the suffix is hardcoded in both providers.

I'm not sure about standard webhook mode because it implements the standard webhook specification. This suggestion is against the spec, so I'm not sure if it makes sense to accommodate it.

[alexbouchardd]

Just adding my 2 cents here, I do think it's reasonable to add new configs here. Ultimately, backward compatibility is a critical necessity.

One way to avoid config creep is to update DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER and equivalent to DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE and in the case where it's '' it would then be infered to be disabled

The message-signature header is difficult because it affects the ability to set prefix. So we can either skip prefix altogether and have to manually include x-flywire- everywhere, or we need to do something else with that header.

We've had other instances where per tenant or per destination override could have been useful, maybe there's a design where relevant env variable can be overridden for a specific tenant/destination

---

@ambroziepaval One possible workaround for the moment is to sign the event yourself and include it in the event.metadata. Those get mapped to HTTP headers and would give you control over the header key and value.

[hiSandog]

Custom signature header names should include validation rules up front. Header names need to reject invalid characters and probably reserve existing delivery headers to avoid collisions. A regression test should configure two destinations with different signature header names and assert signing, retry delivery, and verification docs/examples all use the configured name rather than a hard-coded prefix.

[jcagarcia]

+1 on this — this would be really useful for my team too.

We're in a similar migration scenario: our platform already sends a signature header under a custom name (not the signature pattern Outpost currently produces), and we have an existing contract with clients who validate against that exact header name. Being able to fully override the header name via something like DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME (rather than just the prefix) would let us migrate to Outpost without asking every client to change their signature validation logic — a non-starter for us given how many integrations depend on the current contract.

Backward-compatible opt-in (unset = current behavior) makes this low-risk to add. Would be happy to implement if this gets picked up.

[alexbouchardd]

Sounds good, let us know if you pick it up @jcagarcia otherwise we'll slot it in the roadmap soon!

[ambroziepaval]

Thanks for the discussion, everyone!

A config like DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME would cover our main flow and we can handle our exceptions on our end for now.

We've had other instances where per tenant or per destination override could have been useful, maybe there's a design where relevant env variable can be overridden for a specific tenant/destination

I like that idea a lot. Different clients have unique requirements, so that flexibility would be genuinely useful beyond just this case.

Portal-wise: we're building our own on top of the API, due to some internal requirements.

[alexluong]

@ambroziepaval alrighty, I think the discussion seems clear. Let's go ahead with just DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME. If there's anything else, we can start a separate issue to discuss the other ideas further!

Please open a PR and we'll review. Do let us know if you prefer us to tackle it and we'll find space for it on our roadmap then.

[ambroziepaval]

Thanks @alexluong ! I'll take this one and open a PR soon.

[alexluong]

Hey @ambroziepaval, thanks for the PR and sorry for a bit of confusion. I caught up with @alexbouchardd internally and we agreed on a slightly different design here. The main motivation is that we want to avoid too many configs as mentioned, and also we want to avoid 2 configs that may interfere with each other, for example DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER and DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME.

Here's the new design I'm proposing.

Currently, we have these 4 configs

DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER
DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER
DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER
DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER

We want to replace these with

DESTINATIONS_WEBHOOK_EVENT_ID_HEADER_NAME
DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME
DESTINATIONS_WEBHOOK_TIMESTAMP_HEADER_NAME
DESTINATIONS_WEBHOOK_TOPIC_HEADER_NAME

For each of these config, there should be 3 states

1: nil -> default value
2: value -> use value
3: empty string -> disable

Lastly, we want to consider a backward compat behavior, so ideally we should parse the config and support the default value and interpret that as empty string / disabled behavior. I have some thought on how I'd approach this in our internal/config pkg, and we can chat more in the PR review stage.

PS: we may also consider adding a deprecation warning if the deprecated config is detected

DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER has been deprecated and will be removed in a future version. Set DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE = '' to disable the header.

Let me know what you think! And sorry again for the confusion.

[ambroziepaval]

Thanks @alexluong and @alexbouchardd, this design makes sense and I'm on board. I'll rework the PR to cover all four headers (event-id, signature, timestamp, topic) rather than signature-only, plus the backward compatible parsing of the old DISABLE_* vars with a deprecation warning.

DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER has been deprecated and will be removed in a future version. Set DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE = '' to disable the header.

One thing to pin down on the signature header, since it's the only one with both a name and a value config: the three-state spec disables via an empty name (SIGNATURE_HEADER_NAME=''), but the deprecation example suggests disabling via the template (SIGNATURE_HEADER_TEMPLATE=''). Worth flagging that disabling via the template isn't possible as things stand: explicitly setting SIGNATURE_HEADER_TEMPLATE='' is rejected as a vlidation error ("signature header template is required") rather than disabling the header.

I'd suggest we use an empty SIGNATURE_HEADER_NAME as the disable signal, so all four headers follow the same rule, and keep SIGNATURE_HEADER_TEMPLATE scoped to just the value. Sound good?

[alexluong]

but the deprecation example suggests disabling via the template (SIGNATURE_HEADER_TEMPLATE='').

ah sorry for the confusion, we kept messing up the config names between template & name 😅

I'd suggest we use an empty SIGNATURE_HEADER_NAME as the disable signal, so all four headers follow the same rule, and keep SIGNATURE_HEADER_TEMPLATE scoped to just the value. Sound good?

Yes, this is the intended behavior. I believe we're on the same page here. Let's proceed 💪