Business API

Appearance

Create a webhook​

POST
/v1/webhooks

Requires WEBHOOKS_MANAGE, granted by WEBHOOKS_WRITE (bundles)

Creates a webhook that sends the chosen event types to your URL. The response includes the webhook's signing secret, which you need to verify deliveries: it's shown only once and can't be retrieved later, so store it securely. The URL must use HTTPS and resolve to a public IP address, and a key restricted to sub-accounts can't manage webhooks.

Request Body​

application/json
JSON
{
"url": "https://hooks.example.com/valr",
"eventTypes": [
"FIAT_DEPOSIT_CREDITED",
"FIAT_WITHDRAWAL_STATUS_UPDATE"
],
"description": "Treasury reconciliation"
}

Responses​

Created

application/json
JSON
{
"subscription": {
"identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90",
"scopeKind": "ENTITY",
"scopeLabel": "Entity",
"url": "https://hooks.example.com/valr",
"eventTypes": [
"FIAT_DEPOSIT_CREDITED",
"FIAT_WITHDRAWAL_STATUS_UPDATE"
],
"active": true,
"description": "Treasury reconciliation",
"signingSecretFingerprint": "7477002c",
"createdAt": "2026-10-23T08:00:00.214367Z",
"updatedAt": "2026-10-23T08:00:00.214367Z"
},
"signingSecret": "EXAMPLE-SIGNING-SECRET-do-not-use-000000000"
}

Samples​

Errors

HTTPErrorWhen
400-113INVALID_JSONThe body isn't valid JSON.
400-11INVALID_REQUESTThe body is empty or a field fails validation; validationErrors lists each failing field.
400-18122WEBHOOK_SUBSCRIPTION_LIMIT_REACHEDYour business already has the maximum number of webhooks. Delete one you no longer need, then try again.

Plus the errors common to all signed endpoints.