FIfireblocks
Webhooks V2

Create OAuth credentials

Creates a reusable OAuth client credential set. Attach it to a webhook by passing the returned id as that webhook's webhookOauthId. Several webhooks may share one credential set, so rotating its client secret covers all of them at once. The client secret is write-only and is never returned.

Endpoint Permissions: Owner, Admin, Non-Signing Admin.

post/webhooks_settings/oauth

Request

Headers

Idempotency-Keystring

A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.

Request body

namestring required

A label for this credential set, shown when listing them.

clientIdstring required

OAuth client ID used to authenticate with the token endpoint.

clientSecretstring required

OAuth client secret. Write-only — never returned. Limited to 480 bytes UTF-8 encoded. With client_secret_jwt it signs the assertion rather than being sent.

urlstring required

Token endpoint URL. HTTPS on port 443 only, and the host must resolve publicly — localhost and private, link-local or loopback addresses are rejected.

authMethodstring

How the client credentials reach the token endpoint. client_secret_basic uses an HTTP Basic header, client_secret_post uses form fields in the body, and client_secret_jwt sends a JWT assertion signed with the secret, so the secret itself is never transmitted. Defaults to client_secret_basic.

customJwtClaimsWebhookOauthCustomJwtClaims nullable

Extra claims for the JWT assertion. Used only when authMethod is client_secret_jwt. The usual one to set is aud, which defaults to the token endpoint URL; some authorization servers expect their own identifier instead. A value may be any JSON type except null — null is reserved for deleting a claim on update. iss, sub, jti, iat and exp are set by Fireblocks and cannot be overridden. Names are case-sensitive. The whole object must be under 16 KB. Values are write-only; responses return only the claim names. On update this merges claim by claim rather than replacing — see WebhookOauthCustomJwtClaimsUpdate.

customBodyParamsWebhookOauthCustomBodyParams nullable

Extra parameters for the token request body — scope most commonly, sometimes audience or resource. Applies to every authentication method. Values must be strings, because the token request body is form-encoded rather than JSON. An empty string is allowed. grant_type, client_id, client_secret, client_assertion and client_assertion_type are set by Fireblocks and cannot be overridden. Names are case-sensitive. The whole object must be under 16 KB. Values are write-only; responses return only the parameter names. On update this merges key by key rather than replacing — see WebhookOauthCustomBodyParamsUpdate.

customHeadersWebhookOauthCustomHeaders nullable

Extra HTTP headers for the token request to your authorization server — not for the webhook delivery, which has its own separate customHeaders. A gateway API key is the usual case. Values must be strings; an empty string is allowed. Names are matched case-insensitively, so two names differing only in case are a duplicate. Names are stored and returned lowercased, so X-Api-Key comes back as x-api-key. Content-Type, Content-Length and Host are set by Fireblocks and cannot be overridden. Authorization can be set with client_secret_post or client_secret_jwt, which send the credentials in the body — useful when your token endpoint sits behind a gateway. It is rejected with client_secret_basic, which sends the credentials in that header. Values have no length limit of their own; the whole object must be under 16 KB when serialized as UTF-8. Values are write-only; responses return only the header names. On update this merges name by name rather than replacing — see WebhookOauthCustomHeadersUpdate.

webhookMtlsIdstring uuid nullable

The id of the mTLS configuration presented to the token endpoint, from /v1/webhooks_settings/mtls. It can be the same configuration a webhook uses, so one certificate, signed from GET /v1/webhooks_settings/mtls_csr, serves both the token endpoint and the receiver. Omit, or send null, for a token request without mTLS. Requires the mTLS feature to be enabled for the workspace (403 otherwise), a configuration of this workspace (404 otherwise), and one linked to a private key (400 otherwise).

Example request

{
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "clientSecret": "my-client-secret",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_basic",
  "customJwtClaims": {
    "aud": "https://auth.example.com",
    "email_verified": true
  },
  "customBodyParams": {
    "scope": "payments.read payments.write"
  },
  "customHeaders": {
    "x-api-key": "gateway-key"
  },
  "webhookMtlsId": "6f1b7c62-0f2e-4f1a-9a5e-9f2b1c3d4e5f"
}

Response

created the OAuth credentials successfully

idstring uuid required

The id of the OAuth credentials. Pass this as a webhook's webhookOauthId to attach them.

namestring required

The label given to this credential set.

clientIdstring required

OAuth client ID used to authenticate with the token endpoint.

urlstring required

Token endpoint URL.

authMethodstring required

How the client credentials are presented to the token endpoint: client_secret_basic, client_secret_post or client_secret_jwt. Credentials created without this field report client_secret_basic, which is what they use.

customJwtClaimsstring[]

Names of the additional claims placed in the JWT assertion. Claim values are write-only and are never returned. Absent when no custom claims are configured.

customBodyParamsstring[]

Names of the additional parameters added to the token request body. Parameter values are write-only and are never returned. Absent when no custom parameters are configured.

customHeadersstring[]

Names of the additional HTTP headers added to the token request sent to the authorization server — not to the webhook delivery, which has its own separate customHeaders. Header values are write-only and are never returned. Absent when no custom headers are configured.

webhookMtlsIdstring uuid

The id of the mTLS configuration presented to the token endpoint. Absent when the token request does not use mTLS. Read the certificate from /v1/webhooks_settings/mtls/{id}.

createdAtinteger required

The date and time the OAuth credentials were created, in milliseconds.

updatedAtinteger required

The date and time the OAuth credentials were last updated, in milliseconds.

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_basic",
  "customJwtClaims": [
    "aud",
    "resource"
  ],
  "customBodyParams": [
    "scope"
  ],
  "customHeaders": [
    "X-Api-Key"
  ],
  "webhookMtlsId": "6f1b7c62-0f2e-4f1a-9a5e-9f2b1c3d4e5f",
  "createdAt": 1625097600000,
  "updatedAt": 1625097600000
}

Changes

No recorded changes to this operation across all 1 revision of this API.