---
title: "Create a new webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks V2"]
---

# Create a new webhook

`POST /webhooks`

## Request

- Base URL: `https://api.fireblocks.io/v1`
- URL: `https://api.fireblocks.io/v1/webhooks`
- Auth: none declared
- TypeScript: <https://skmtc.dev/fireblocks/apis/fireblocks-api/docs/webhooks/post.ts> (a function with typed inputs; its response is checked against the schema)

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

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

## Headers

- `Idempotency-Key` string

## Request body

- CreateWebhookRequest
  - `url` string, required: The url of the webhook where notifications will be sent. URL must be valid, unique and https.
  - `description` string: description of the webhook. should not contain special characters.
  - `events` WebhookEvent[], required: event types the webhook will subscribe to
  - `enabled` boolean: The status of the webhook. If false, the webhook will not receive notifications.
  - `webhookMtlsId` string, 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.
  - `webhookOauthId` string, 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.
  - `customHeaders` WebhookCustomHeaders: 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.

## Response `201`

created new webhook successfully

- Webhook
  - `id` string, uuid, required: The id of the webhook
  - `url` string, required: The url of the webhook where notifications will be sent. Must be a valid URL and https.
  - `description` string: description of the webhook of what it is used for
  - `events` WebhookEvent[], required: The events that the webhook will be subscribed to
  - `status` 'DISABLED' | 'ENABLED' | 'SUSPENDED', required: The status of the webhook
  - `createdAt` integer, required: The date and time the webhook was created in milliseconds
  - `updatedAt` integer, required: The date and time the webhook was last updated in milliseconds
  - `webhookMtlsId` string, 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.
  - `webhookOauthId` string, 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}`.
  - `customHeaders` string[]: Names of the custom headers configured for this webhook. Header values are never returned.

## Other responses

- `default`: Error Response

---

[API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)