Skip to main content
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. 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.
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 certificate-bound tokens require it to be the same one. See 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: 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: fetch the Fireblocks CSR, sign it with your CA, and create a certificate record your webhooks reference.
  • OAuth 2.0 for webhooks: create a credentials record with a token endpoint and client authentication method, optionally with mTLS on the token endpoint connection.
  • Custom headers for webhooks: attach up to 10 static headers to every delivery for a webhook.