Create a new webhook

POST

webhooks

TypeScript

const response: Promise<FireblocksResponse<Webhook>> = fireblocks.webhooksV2.createWebhook(webhooksV2ApiCreateWebhookRequest);

curl --request POST \
  --url https://api.fireblocks.io/v1/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/webhook",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "description": "This webhook is used for transactions notifications",
  "enabled": false,
  "mtls": {
    "clientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "oauth": {
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "url": "https://auth.example.com/oauth/token",
    "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "customHeaders": {
    "X-Gateway-Key": "abc123",
    "X-Region-Tag": "eu",
    "X-Forwarded-For": [
      "203.0.113.7",
      "198.51.100.4"
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://example.com/webhook',
    events: ['transaction.created', 'transaction.status.updated'],
    description: 'This webhook is used for transactions notifications',
    enabled: false,
    mtls: {
      clientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
    },
    oauth: {
      clientId: 'my-client-id',
      clientSecret: 'my-client-secret',
      url: 'https://auth.example.com/oauth/token',
      mtlsClientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
    },
    customHeaders: {
      'X-Gateway-Key': 'abc123',
      'X-Region-Tag': 'eu',
      'X-Forwarded-For': ['203.0.113.7', '198.51.100.4']
    }
  })
};

fetch('https://api.fireblocks.io/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com/webhook',
    'events' => [
        'transaction.created',
        'transaction.status.updated'
    ],
    'description' => 'This webhook is used for transactions notifications',
    'enabled' => false,
    'mtls' => [
        'clientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
    ],
    'oauth' => [
        'clientId' => 'my-client-id',
        'clientSecret' => 'my-client-secret',
        'url' => 'https://auth.example.com/oauth/token',
        'mtlsClientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
    ],
    'customHeaders' => [
        'X-Gateway-Key' => 'abc123',
        'X-Region-Tag' => 'eu',
        'X-Forwarded-For' => [
                '203.0.113.7',
                '198.51.100.4'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"transaction.created\",\n    \"transaction.status.updated\"\n  ],\n  \"description\": \"This webhook is used for transactions notifications\",\n  \"enabled\": false,\n  \"mtls\": {\n    \"clientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"oauth\": {\n    \"clientId\": \"my-client-id\",\n    \"clientSecret\": \"my-client-secret\",\n    \"url\": \"https://auth.example.com/oauth/token\",\n    \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"customHeaders\": {\n    \"X-Gateway-Key\": \"abc123\",\n    \"X-Region-Tag\": \"eu\",\n    \"X-Forwarded-For\": [\n      \"203.0.113.7\",\n      \"198.51.100.4\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"transaction.created\",\n    \"transaction.status.updated\"\n  ],\n  \"description\": \"This webhook is used for transactions notifications\",\n  \"enabled\": false,\n  \"mtls\": {\n    \"clientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"oauth\": {\n    \"clientId\": \"my-client-id\",\n    \"clientSecret\": \"my-client-secret\",\n    \"url\": \"https://auth.example.com/oauth/token\",\n    \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"customHeaders\": {\n    \"X-Gateway-Key\": \"abc123\",\n    \"X-Region-Tag\": \"eu\",\n    \"X-Forwarded-For\": [\n      \"203.0.113.7\",\n      \"198.51.100.4\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://example.com/webhook",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "status": "ENABLED",
  "createdAt": 1625126400000,
  "updatedAt": 1625126400000,
  "description": "This webhook is used for transactions notifications",
  "mtls": {
    "clientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "oauth": {
    "clientId": "my-client-id",
    "url": "https://auth.example.com/oauth/token",
    "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "customHeaders": [
    "x-gateway-key",
    "x-region-tag"
  ]
}

{
  "message": "<string>",
  "code": 123
}

Headers

Idempotency-Key

string

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.

Body

application/json

url

string

required

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

Minimum string length: 1

Example:

"https://example.com/webhook"

events

enum<string>[]

required

event types the webhook will subscribe to

Available options:

transaction.created,

transaction.status.updated,

transaction.approval_status.updated,

transaction.network_records.processing_completed,

transaction.alert.stuck,

external_wallet.asset.added,

external_wallet.asset.removed,

internal_wallet.asset.added,

internal_wallet.asset.removed,

contract_wallet.asset.added,

contract_wallet.asset.removed,

vault_account.created,

vault_account.asset.added,

vault_account.asset.balance_updated,

vault_account.nft.balance_updated,

vault_account.bulk_create_job_started,

vault_account.bulk_create_job_ended,

vault_account.asset.bulk_add_job_started,

vault_account.asset.bulk_add_job_ended,

embedded_wallet.status.updated,

embedded_wallet.created,

embedded_wallet.asset.balance_updated,

embedded_wallet.asset.added,

embedded_wallet.account.created,

embedded_wallet.device.added,

onchain_data.updated,

connection.added,

connection.removed,

connection.request.waiting_peer_approval,

connection.request.rejected_by_peer,

exchange_account.connected,

fiat_account.connected,

connected_account.connected,

ticket.created,

ticket.submitted,

ticket.expired,

ticket.canceled,

ticket.fulfilled,

ticket.counterparty.added,

ticket.counterparty_external_id.set,

ticket.note.added,

ticket.expires_at.set,

ticket.expires_in.set,

ticket.term.added,

ticket.term.updated,

ticket.term.deleted,

ticket.term.funded,

ticket.term.manually_funded,

ticket.term.funding_canceled,

ticket.term.funding_failed,

ticket.term.funding_completed,

ticket.term.transaction_status_changed,

settlement.created,

order.updated,

automation_execution.update

Example:

[
  "transaction.created",
  "transaction.status.updated"
]

description

string

description of the webhook. should not contain special characters.

Minimum string length: 1

Example:

"This webhook is used for transactions notifications"

enabled

boolean

default:true

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

Example:

false

mtls

object | null

mTLS configuration for the webhook. On responses, present only when a signed client certificate is set. On requests, provide a signed client certificate to enable mTLS, or null to remove it.

Show child attributes

oauth

object | null

OAuth 2.0 client credentials configuration for the webhook. When set, the webhook dispatcher fetches a bearer token from the configured token endpoint before each delivery and attaches it as Authorization: Bearer {token}. Send null to remove OAuth configuration entirely.

Show child attributes

customHeaders

object

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 accepts only a string. An empty array is rejected — leave the name out instead. At most 10 header lines in total, counted per array element rather than per name. 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. When this webhook has OAuth credentials attached, an Authorization value you set and the bearer token are both sent as separate header lines. Values are write-only; responses return only the header names.

Show child attributes

Example:

{
  "X-Gateway-Key": "abc123",
  "X-Region-Tag": "eu",
  "X-Forwarded-For": ["203.0.113.7", "198.51.100.4"]
}

Response

created new webhook successfully

string<uuid>

required

The id of the webhook

Example:

"123e4567-e89b-12d3-a456-426614174000"

url

string

required

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

Minimum string length: 1

Example:

"https://example.com/webhook"

events

enum<string>[]

required

The events that the webhook will be subscribed to

Available options:

transaction.created,

transaction.status.updated,

transaction.approval_status.updated,

transaction.network_records.processing_completed,

transaction.alert.stuck,

external_wallet.asset.added,

external_wallet.asset.removed,

internal_wallet.asset.added,

internal_wallet.asset.removed,

contract_wallet.asset.added,

contract_wallet.asset.removed,

vault_account.created,

vault_account.asset.added,

vault_account.asset.balance_updated,

vault_account.nft.balance_updated,

vault_account.bulk_create_job_started,

vault_account.bulk_create_job_ended,

vault_account.asset.bulk_add_job_started,

vault_account.asset.bulk_add_job_ended,

embedded_wallet.status.updated,

embedded_wallet.created,

embedded_wallet.asset.balance_updated,

embedded_wallet.asset.added,

embedded_wallet.account.created,

embedded_wallet.device.added,

onchain_data.updated,

connection.added,

connection.removed,

connection.request.waiting_peer_approval,

connection.request.rejected_by_peer,

exchange_account.connected,

fiat_account.connected,

connected_account.connected,

ticket.created,

ticket.submitted,

ticket.expired,

ticket.canceled,

ticket.fulfilled,

ticket.counterparty.added,

ticket.counterparty_external_id.set,

ticket.note.added,

ticket.expires_at.set,

ticket.expires_in.set,

ticket.term.added,

ticket.term.updated,

ticket.term.deleted,

ticket.term.funded,

ticket.term.manually_funded,

ticket.term.funding_canceled,

ticket.term.funding_failed,

ticket.term.funding_completed,

ticket.term.transaction_status_changed,

settlement.created,

order.updated,

automation_execution.update

Example:

[
  "transaction.created",
  "transaction.status.updated"
]

status

enum<string>

required

The status of the webhook

Available options:

DISABLED,

ENABLED,

SUSPENDED

Example:

"ENABLED"

createdAt

integer<int64>

required

The date and time the webhook was created in milliseconds

Example:

1625126400000

updatedAt

integer<int64>

required

The date and time the webhook was last updated in milliseconds

Example:

1625126400000

description

string

description of the webhook of what it is used for

Minimum string length: 1

Example:

"This webhook is used for transactions notifications"

mtls

object | null

mTLS configuration for the webhook. On responses, present only when a signed client certificate is set. On requests, provide a signed client certificate to enable mTLS, or null to remove it.

Show child attributes

oauth

object

OAuth 2.0 client credentials configuration for the webhook. Present only when OAuth is configured. The clientSecret is write-only and is never returned.

Show child attributes

customHeaders

string[]

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

Example:

["x-gateway-key", "x-region-tag"]

⌘I

TypeScript

const response: Promise<FireblocksResponse<Webhook>> = fireblocks.webhooksV2.createWebhook(webhooksV2ApiCreateWebhookRequest);

curl --request POST \
  --url https://api.fireblocks.io/v1/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/webhook",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "description": "This webhook is used for transactions notifications",
  "enabled": false,
  "mtls": {
    "clientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "oauth": {
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "url": "https://auth.example.com/oauth/token",
    "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "customHeaders": {
    "X-Gateway-Key": "abc123",
    "X-Region-Tag": "eu",
    "X-Forwarded-For": [
      "203.0.113.7",
      "198.51.100.4"
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://example.com/webhook',
    events: ['transaction.created', 'transaction.status.updated'],
    description: 'This webhook is used for transactions notifications',
    enabled: false,
    mtls: {
      clientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
    },
    oauth: {
      clientId: 'my-client-id',
      clientSecret: 'my-client-secret',
      url: 'https://auth.example.com/oauth/token',
      mtlsClientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
    },
    customHeaders: {
      'X-Gateway-Key': 'abc123',
      'X-Region-Tag': 'eu',
      'X-Forwarded-For': ['203.0.113.7', '198.51.100.4']
    }
  })
};

fetch('https://api.fireblocks.io/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com/webhook',
    'events' => [
        'transaction.created',
        'transaction.status.updated'
    ],
    'description' => 'This webhook is used for transactions notifications',
    'enabled' => false,
    'mtls' => [
        'clientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
    ],
    'oauth' => [
        'clientId' => 'my-client-id',
        'clientSecret' => 'my-client-secret',
        'url' => 'https://auth.example.com/oauth/token',
        'mtlsClientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
    ],
    'customHeaders' => [
        'X-Gateway-Key' => 'abc123',
        'X-Region-Tag' => 'eu',
        'X-Forwarded-For' => [
                '203.0.113.7',
                '198.51.100.4'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"transaction.created\",\n    \"transaction.status.updated\"\n  ],\n  \"description\": \"This webhook is used for transactions notifications\",\n  \"enabled\": false,\n  \"mtls\": {\n    \"clientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"oauth\": {\n    \"clientId\": \"my-client-id\",\n    \"clientSecret\": \"my-client-secret\",\n    \"url\": \"https://auth.example.com/oauth/token\",\n    \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"customHeaders\": {\n    \"X-Gateway-Key\": \"abc123\",\n    \"X-Region-Tag\": \"eu\",\n    \"X-Forwarded-For\": [\n      \"203.0.113.7\",\n      \"198.51.100.4\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"transaction.created\",\n    \"transaction.status.updated\"\n  ],\n  \"description\": \"This webhook is used for transactions notifications\",\n  \"enabled\": false,\n  \"mtls\": {\n    \"clientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"oauth\": {\n    \"clientId\": \"my-client-id\",\n    \"clientSecret\": \"my-client-secret\",\n    \"url\": \"https://auth.example.com/oauth/token\",\n    \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n  },\n  \"customHeaders\": {\n    \"X-Gateway-Key\": \"abc123\",\n    \"X-Region-Tag\": \"eu\",\n    \"X-Forwarded-For\": [\n      \"203.0.113.7\",\n      \"198.51.100.4\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://example.com/webhook",
  "events": [
    "transaction.created",
    "transaction.status.updated"
  ],
  "status": "ENABLED",
  "createdAt": 1625126400000,
  "updatedAt": 1625126400000,
  "description": "This webhook is used for transactions notifications",
  "mtls": {
    "clientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "oauth": {
    "clientId": "my-client-id",
    "url": "https://auth.example.com/oauth/token",
    "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "customHeaders": [
    "x-gateway-key",
    "x-region-tag"
  ]
}

{
  "message": "<string>",
  "code": 123
}

Introduction

Errors & Statuses

Data Objects

API Endpoints

Headers

Body

Response