FIfireblocks
Webhooks V2

Update OAuth credentials

Updates only the fields present in the request; anything omitted is left as it is. Sending clientSecret on its own rotates the secret for every webhook using these credentials.

customJwtClaims, customBodyParams and customHeaders are all merged key by key rather than replaced, the same way a webhook's own customHeaders behaves: a key sent with a value is added or overwritten, a key sent with a null value is deleted, and a key you omit is left alone. Setting one of the three to null as a whole clears that map, which is the quick way to empty it without naming every key. There is no ambiguity between the two uses of null — one names an entry to delete, the other names the field. A claim cannot be set to JSON null, though, on this endpoint or on create, because null is spent on deletion. webhookMtlsId is a scalar rather than a map, so null there does remove it.

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

patch/webhooks_settings/oauth/{webhookOauthId}

Request

Path parameters

webhookOauthIdstring uuid required
Example:44fcead0-7053-4831-a53a-df7fb90d440f

The unique identifier of the OAuth credentials

Request body

namestring

A label for this credential set. Omit to leave it unchanged.

clientIdstring

OAuth client ID. Omit to leave it unchanged.

clientSecretstring

A new OAuth client secret. Limited to 480 bytes when UTF-8 encoded, so a secret using non-ASCII characters fits fewer than 480 of them. Write-only — never returned in any response. Send this on its own to rotate the secret without changing anything else. Omit to leave it unchanged.

urlstring

Token endpoint URL. HTTPS on port 443 only, and the host must resolve publicly. Omit to leave it unchanged.

authMethodstring

client_secret_basic, client_secret_post or client_secret_jwt. Omit to leave it unchanged — it does not revert to the default.

customJwtClaimsWebhookOauthCustomJwtClaimsUpdate nullable

A delta applied to the JWT assertion claims. A claim with a value is added or replaced, a claim with null is deleted, and a claim you leave out is untouched. So { "aud": "https://auth.example.com", "resource": null } sets aud, drops resource, and changes nothing else. Send customJwtClaims: null to clear every claim in one call. That does not collide with a null value on a name: one names the claim to delete, the other names the whole field. Same rules as on create: any JSON type except null, iss/sub/jti/iat/exp reserved, names case-sensitive, resulting set under 16 KB, values write-only.

customBodyParamsWebhookOauthCustomBodyParamsUpdate nullable

A delta applied to the token request body parameters. A parameter with a value is added or replaced, a parameter with null is deleted, and one you leave out is untouched. So { "scope": "payments.read", "audience": null } sets scope, drops audience, and changes nothing else. Send customBodyParams: null to clear every parameter in one call. That does not collide with a null value on a name: one names the parameter to delete, the other names the whole field. Same rules as on create: string values only, grant_type/client_id/client_secret/ client_assertion/client_assertion_type reserved, names case-sensitive, resulting set under 16 KB, values write-only.

customHeadersWebhookOauthCustomHeadersUpdate nullable

A delta applied to the token request headers — not the webhook delivery headers. A header with a value is added or replaced, a header with null is deleted, and one you leave out is untouched. So { "X-Api-Key": "new-key", "X-Tenant": null } rotates X-Api-Key, drops X-Tenant, and changes nothing else. Send customHeaders: null to clear every header in one call. That does not collide with a null value on a name: one names the header to delete, the other names the whole field. Names are case-insensitive, so a null under one casing deletes a header stored under another, and names are stored and returned lowercased. Same rules as on create: string values only, Content-Type, Content-Length and Host reserved, Authorization only with client_secret_post or client_secret_jwt, resulting set under 16 KB, values write-only.

webhookMtlsIdstring uuid nullable

The id of the mTLS configuration presented to the token endpoint, from /v1/webhooks_settings/mtls. Omit to leave it unchanged, or send null to stop using mTLS for the token request. 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-new-client-secret",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_jwt",
  "customJwtClaims": {
    "aud": "https://auth.example.com",
    "resource": null
  },
  "customBodyParams": {
    "scope": "payments.read payments.write",
    "audience": null
  },
  "customHeaders": {
    "x-api-key": "gateway-key",
    "x-tenant": null
  },
  "webhookMtlsId": "6f1b7c62-0f2e-4f1a-9a5e-9f2b1c3d4e5f"
}

Response

Updated OAuth credentials object

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.