# Custom Webhook Headers

Published: 2026-04-15

> Attach custom HTTP headers to any webhook so your endpoint can authenticate incoming events, route them to the right tenant, or integrate with auth-gated infrastructure without…

## Custom Webhook Headers

Attach custom HTTP headers to any webhook so your endpoint can authenticate incoming events, route them to the right tenant, or integrate with auth-gated infrastructure without a proxy in between.

### What's new?

**Custom headers on webhooks**

- Pass a `headers` object on [`POST /webhooks/attach`](/api-reference/webhooks/attach-webhook) when creating a new webhook **or** when attaching an existing `webhookId`
- Supplying `headers` with an existing `webhookId` **overwrites** the stored headers — omit the field to leave existing headers unchanged
- Headers are returned on every webhook response (`list_webhooks`, `get_webhooks`, `attach_webhook`) so you always see what will be sent
- Every webhook delivery includes the headers you configured alongside the standard `PINNACLE-SIGNING-SECRET`

**Header rules**

- Header names must match `^[A-Za-z0-9][A-Za-z0-9_-]*$` — start with a letter or digit, contain only letters, digits, `-`, or `_`
- Names are case-insensitive (per [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-field-names)) and normalized to uppercase before storage
- Values must be strings
- The reserved `PINNACLE-SIGNING-SECRET` header is silently stripped and cannot be overridden — Pinnacle always sets it with your signing secret for request verification

**Use cases**

- Add an `AUTHORIZATION: Bearer …` header so your webhook endpoint can sit behind the same auth as the rest of your API
- Include a tenant identifier (`X-TENANT-ID`) to route multi-tenant deliveries without parsing the payload
- Pass an `X-API-KEY` for legacy systems that require pre-shared keys

[View API reference →](/api-reference/webhooks/attach-webhook)

**Note:** Have questions? Reach out to us - founders@pinnacle.sh