FIfireblocks
Webhooks V2

Create a new webhook

Creates a new webhook, which will be triggered on the specified events

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

post/webhooks

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

urlstring required

The url of the webhook where notifications will be sent. URL must be valid, unique and https.

descriptionstring

description of the webhook. should not contain special characters.

eventsWebhookEvent[] required

event types the webhook will subscribe to

enabledboolean

The status of the webhook. If false, the webhook will not receive notifications.

webhookMtlsIdstring uuid nullable

The id of the mTLS configuration this webhook presents when delivering, from /v1/webhooks_settings/mtls. Several webhooks may share one configuration, so replacing its certificate covers all of them at once. Send null to stop using mTLS for this webhook.

webhookOauthIdstring uuid nullable

The id of the OAuth credentials this webhook authenticates with, from /v1/webhooks_settings/oauth. Several webhooks may share one credential set, so rotating its client secret covers all of them at once. Send null to stop using OAuth for this webhook. Cannot be combined with an authorization custom header on the same webhook; a request that would leave both set is rejected.

customHeadersWebhookCustomHeaders

Custom HTTP headers attached to every notification delivered by this webhook. A value is a string, sent as one header line, or an array of strings, sent as one header line per element under the same name. Cookie and Authorization accept only a string. An empty array is rejected — leave the name out instead. At most 10 headers, counted by name — an array value counts once, however many lines it sends. Names must be valid HTTP header tokens, are case-insensitive, and are at most 128 characters. A value may be empty and has no length limit of its own; the whole object must be under 16 KB when serialized as UTF-8. A value that large may still be refused by your own endpoint, since web servers commonly cap the whole request header block at around 8 KB. Reserved names: Host, Content-Type, Content-Length, Transfer-Encoding, Connection, User-Agent, Accept, Accept-Encoding, Fireblocks-Signature, Fireblocks-Webhook-Signature. Authorization may be set, but not together with webhookOauthId; a request that would leave both set is rejected. Values are write-only; responses return only the header names.

Example request

{
  "url": "https://example.com/webhook",
  "description": "This webhook is used for transactions notifications",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "webhookMtlsId": "6f1b7c62-0f2e-4f1a-9a5e-9f2b1c3d4e5f",
  "webhookOauthId": "123e4567-e89b-12d3-a456-426614174000",
  "customHeaders": {
    "X-Gateway-Key": "abc123",
    "X-Region-Tag": "eu",
    "X-Forwarded-For": [
      "203.0.113.7",
      "198.51.100.4"
    ]
  }
}

Response

created new webhook successfully

idstring uuid required

The id of the webhook

urlstring required

The url of the webhook where notifications will be sent. Must be a valid URL and https.

descriptionstring

description of the webhook of what it is used for

eventsWebhookEvent[] required

The events that the webhook will be subscribed to

status'DISABLED' | 'ENABLED' | 'SUSPENDED' required

The status of the webhook

createdAtinteger required

The date and time the webhook was created in milliseconds

updatedAtinteger required

The date and time the webhook was last updated in milliseconds

webhookMtlsIdstring uuid

The id of the mTLS configuration this webhook presents when delivering, from /v1/webhooks_settings/mtls. Absent when the webhook does not use mTLS.

webhookOauthIdstring uuid

The id of the OAuth credentials this webhook authenticates with. Absent when the webhook does not use OAuth. Read the credentials themselves from /v1/webhooks_settings/oauth/{webhookOauthId}.

customHeadersstring[]

Names of the custom headers configured for this webhook. Header values are never returned.

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://example.com/webhook",
  "description": "This webhook is used for transactions notifications",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "status": "ENABLED",
  "createdAt": 1625126400000,
  "updatedAt": 1625126400000,
  "webhookMtlsId": "6f1b7c62-0f2e-4f1a-9a5e-9f2b1c3d4e5f",
  "webhookOauthId": "123e4567-e89b-12d3-a456-426614174000",
  "customHeaders": [
    "x-gateway-key",
    "x-region-tag"
  ]
}

Changes

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