> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Webhook Controls

> Authenticate Fireblocks at your webhook endpoint with mTLS or OAuth 2.0, and send the static values your gateway expects with custom headers.

Your security policy may require that the caller connecting to your endpoint is authenticated, not only that the payload it sends is verified. This is most often driven by an organization's own security policy, and it can also apply in regulated environments.

Advanced Webhook Controls let your endpoint authenticate Fireblocks with mTLS or OAuth, and pass the static values your gateway expects with custom headers. Any combination can apply to the same webhook.

This is in addition to the JWS signature every Fireblocks webhook already carries on the body, which verifies the payload rather than the caller. See [Validating webhooks](https://developers.fireblocks.com/reference/validating-webhooks.md).

| Control | Layer | Use when |
| - | - | - |
| [Mutual TLS (mTLS)](https://developers.fireblocks.com/reference/webhooks-mtls.md) | Transport | Your endpoint must authenticate Fireblocks during the TLS handshake, before any request data is exchanged |
| [OAuth 2.0](https://developers.fireblocks.com/reference/webhooks-oauth.md) | Application, dynamic | Your receiver sits behind an authorization server and requires a valid bearer token on every request |
| [Custom headers](https://developers.fireblocks.com/reference/webhooks-custom-headers.md) | Application, static | Your gateway or WAF requires a fixed value on inbound requests |

The three controls are not substitutes for one another. mTLS proves who is connecting, OAuth proves the request carries a currently valid credential, and custom headers carry a static value your infrastructure expects. Combine them as your policy requires.

All three are configured through the API. The Fireblocks Console is read-only for these controls. It shows which webhooks use mTLS or OAuth, and each mTLS certificate’s expiry date.

> [!NOTE]
>
> **Availability:** Advanced Webhook Controls are available to Enterprise customers and above. Contact your Customer Success Manager to enable them for your workspace.

## Combining controls

If your token endpoint requires mTLS, point the OAuth record at an mTLS record with `webhookMtlsId`. It can be the same mTLS record your webhook uses, so one certificate serves both connections and is rotated once. [RFC 8705](https://www.rfc-editor.org/rfc/rfc8705) certificate-bound tokens require it to be the same one. See [mTLS on the token request](https://developers.fireblocks.com/reference/webhooks-mtls.md#mtls-on-the-token-request).

OAuth and a static `authorization` custom header cannot be used on the same webhook, because Fireblocks sets the `Authorization` header itself from the OAuth record. A request that would leave a webhook with both is rejected. Every other custom header works alongside OAuth.

## How configuration is stored

mTLS certificates and OAuth credentials are reusable records in your workspace, each with its own ID, and a webhook points at them:

| Control | Configured at | Referenced by |
| - | - | - |
| mTLS | `/v1/webhooks_settings/mtls` | `webhookMtlsId` on the webhook, and on an OAuth record for the token request |
| OAuth 2.0 | `/v1/webhooks_settings/oauth` | `webhookOauthId` on the webhook |
| Custom headers | On the webhook itself | Not applicable |

One record can back many webhooks, and an mTLS record can also back OAuth records, so you enter a certificate or a client secret once and rotate it in a single call. Deleting a record is refused while anything still references it, so a control cannot silently stop on a webhook you have forgotten about. Passing `forceDelete=true` detaches the record from every webhook and OAuth record that references it, then deletes it. Those webhooks keep delivering, but without that control. An endpoint that requires it will reject them.

Custom headers are set directly on each webhook, because their values are specific to the endpoint receiving them.

Every control is optional per webhook, so webhooks with and without them run side by side in the same workspace.

## Get started

* [mTLS for webhooks](https://developers.fireblocks.com/reference/webhooks-mtls.md): fetch the Fireblocks CSR, sign it with your CA, and create a certificate record your webhooks reference.
* [OAuth 2.0 for webhooks](https://developers.fireblocks.com/reference/webhooks-oauth.md): create a credentials record with a token endpoint and client authentication method, optionally with mTLS on the token endpoint connection.
* [Custom headers for webhooks](https://developers.fireblocks.com/reference/webhooks-custom-headers.md): attach up to 10 static headers to every delivery for a webhook.