Webhook Events

Event envelope

All webhook events use a JSON envelope:

{
  "id": "event-id",
  "type": "transfer.completed",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "resource-id",
    "status": "complete"
  }
}

Field	Type	Description
`id`	string	Stable event identifier (the event ID). Use this for deduplication. This is not the same as `data.id`.
`type`	string	Event type, such as `transfer.completed`.
`created`	string	UTC timestamp when the event was created.
`data`	object	Event-specific payload. `data.id` is the resource ID (e.g., transfer ID or payment ID), which may differ from the event `id`.

Managing accounts and event fan-in

If your integration uses managed accounts or individual accounts, a single managing account can receive events for every account it manages.

A webhook subscription owned by a managing account receives events for every account it manages, plus its own.
A webhook subscription owned by a managed account receives only that account’s own events.

This is derived from the subscription’s owner. There is no scope parameter to set when creating the subscription. To attribute an event to the correct managed account, read data.account_id from the payload. It is present on payment.completed, transfer.created, and transfer.failed, in addition to the account.verification.* events that already carry it. Your handler should branch on type.

switch (event.type) {
  case "transfer.completed":
    await handleTransferCompleted(event.data);
    break;
  case "transfer.failed":
    await handleTransferFailed(event.data);
    break;
  case "payment.completed":
    await handlePaymentCompleted(event.data);
    break;
  default:
    // Unknown future event type.
    // Store and acknowledge safely.
    break;
}

`transfer.created`

Emitted when a Brale transfer is created. Example:

{
  "id": "3D4ExampleEventId",
  "type": "transfer.created",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "3D4ExampleTransferId",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "pending",
    "amount": {
      "value": "100.00",
      "currency": "USD"
    }
  }
}

Notes:

Treat data.id as the transfer ID.
data.account_id identifies the account the transfer belongs to. Managing accounts use this to attribute events to a specific managed account.
Additional fields may be present as the transfer schema evolves.
Your integration should ignore unknown fields.

`transfer.completed`

Emitted when a Brale transfer reaches complete status. Use this event to replace polling transfer status. Example:

{
  "id": "3D4ExampleEventId",
  "type": "transfer.completed",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "3D4ExampleTransferId",
    "status": "complete",
    "amount": {
      "value": "100.00",
      "currency": "USD"
    }
  }
}

Notes:

Treat data.id as the transfer ID.
Treat data.status as the completed transfer state. The event name is transfer.completed; the API status is complete.
For outbound domestic wires, transfer.completed is not a guarantee that the payout cannot be returned later. If the bank returns the wire, the same transfer moves to failed and Brale emits transfer.failed. Keep accepting transfer.failed for transfers you recorded as complete.
Additional fields may be present as the transfer schema evolves.
Your integration should ignore unknown fields.

`transfer.failed`

Emitted when a Brale transfer reaches failed status. Use this event to react to permanent transfer failures (e.g., ACH returns, outbound domestic wire returns, or other rail/provider failures). For ACH-specific return details, inspect data.failure.ach_return. For wire return details, inspect data.failure.wire_return. Example:

{
  "id": "3D4ExampleEventId",
  "type": "transfer.failed",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "3D4ExampleTransferId",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "failed",
    "amount": {
      "value": "100.00",
      "currency": "USD"
    },
    "failure": {
      "type": "ach_return",
      "occurred_at": "2026-04-29T23:29:55.000000Z",
      "retriable": false,
      "ach_return": {
        "code": "R01",
        "reason": "Insufficient Funds",
        "category": "administrative"
      }
    }
  }
}

Notes:

Treat data.id as the transfer ID.
data.account_id identifies the account the transfer belongs to. Managing accounts use this to attribute events to a specific managed account.
Treat data.status as the failed transfer state.
data.failure is usually populated for transfer.failed, but may be null when Brale does not have structured failure details. Always null-check before reading nested fields.
data.failure.retriable indicates whether the failure is retriable. Spelled retriable, not retryable.
data.failure.ach_return is only set for ACH return failures. See the transfer failure field for the full schema.
Additional fields may be present as the transfer schema evolves.
Your integration should ignore unknown fields.

Returned outbound wires

Brale uses the existing transfer.failed event for returned outbound domestic wires. There is no separate returned or refunded event. The same transfer can produce transfer.completed and later transfer.failed if the wire is returned after completion. Example (illustrative, not an observed production payload):

{
  "id": "3D4ExampleEventId",
  "type": "transfer.failed",
  "created": "2026-10-06T18:30:05.000000Z",
  "data": {
    "id": "3D4ExampleTransferId",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "failed",
    "amount": {
      "value": "100.00",
      "currency": "USD"
    },
    "failure": {
      "type": "wire_return",
      "occurred_at": "2026-10-06T18:30:00Z",
      "retriable": false,
      "ach_return": null,
      "wire_return": {
        "code": "AC04",
        "reason": "Account closed"
      }
    }
  }
}

How to handle it:

Read data.status for the payout state. Read data.failure.type for the failure classification when data.failure is present.
When data.failure.type is wire_return, read data.failure.wire_return, not data.failure.ach_return.
Do not require an ACH return code or a specific bank reason code to recognize a wire return. data.failure.wire_return.code is WIRE_RETURN when the provider supplies no code, and data.failure.wire_return.reason can be null.
Missing structured failure details do not mean the transfer succeeded. If data.status is failed, update your records even when data.failure is null.
transfer.failed confirms that the payout failed or was returned. It does not confirm that stablecoins were refunded or that refunded funds are available.
Track payout state, return classification, and any refund credit separately.
Do not assume event ordering. Retrieve the latest transfer when you need to reconcile its current state.

`payment.completed`

Emitted when a payment reaches complete status. Example:

{
  "id": "3D4ExamplePaymentId",
  "type": "payment.completed",
  "created": "2026-04-28T21:30:00.000000Z",
  "data": {
    "id": "3D4ExamplePaymentId",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "complete",
    "amount": {
      "value": "1000.00",
      "currency": "USD"
    },
    "direction": "inbound",
    "type": "wire",
    "inserted_at": "2026-04-28T20:00:00.000000Z",
    "updated_at": "2026-04-28T21:30:00.000000Z"
  }
}

Notes:

data.account_id identifies the account the payment belongs to. Managing accounts use this to attribute events to a specific managed account.
Brale also emits payment.completed for inbound payments created by Simulate an Automation deposit on testnet. There is no simulation-specific webhook type, so the same handler covers simulated and real deposits.

`transfer.canceled`

Emitted when a Brale transfer is canceled. Example:

{
  "id": "3D4ExampleEventId",
  "type": "transfer.canceled",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "3D4ExampleTransferId",
    "status": "canceled",
    "amount": {
      "value": "100.00",
      "currency": "USD"
    }
  }
}

Notes:

Treat data.id as the transfer ID.
Treat data.status as the canceled transfer state.
Additional fields may be present as the transfer schema evolves.
Your integration should ignore unknown fields.

`account.verification.documents_required`

Emitted when Brale’s KYB review determines one or more documents must be uploaded. Use this event to prompt the account holder to submit the requested documents. For each document with status: "pending_upload", stage the file (use document_kind and person_label from the payload), then link staged submissions. You can also poll required documents instead of using this webhook. Example:

{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "type": "account.verification.documents_required",
  "created": "2026-06-09T14:32:00Z",
  "data": {
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "updated_at": "2026-06-09T14:32:00Z",
    "documents": [
      {
        "document_kind": "certificate_of_good_standing",
        "document_type": "business_document",
        "display_name": "Certificate of Good Standing",
        "status": "pending_upload",
        "person_label": null
      },
      {
        "document_kind": "government_photo_id",
        "document_type": "individual_document",
        "display_name": "Government-issued photo ID",
        "status": "pending_upload",
        "person_label": "Jane Doe"
      }
    ]
  }
}

Notes:

Treat data.account_id as the account ID.
Each entry in data.documents describes a required document. status is pending_upload until the document is submitted.
Include person_label when staging individual (KYC) documents.
Your integration should ignore unknown fields.

`account.verification.completed`

Emitted when account verification completes and the account is enabled. Example:

{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "type": "account.verification.completed",
  "created": "2026-06-09T16:00:00Z",
  "data": {
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "complete",
    "updated_at": "2026-06-09T16:00:00Z"
  }
}

Notes:

Treat data.account_id as the account ID.
Treat data.status as the completed verification state (complete).
This event fires only when the account reaches complete status.
Your integration should ignore unknown fields.

`account.verification.rejected`

Emitted when account verification is declined. This is the terminal outcome for a review: the account will not become complete on its own, and no further verification events follow. Example:

{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "type": "account.verification.rejected",
  "created": "2026-06-09T16:00:00Z",
  "data": {
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "rejected",
    "updated_at": "2026-06-09T16:00:00Z"
  }
}

Notes:

Treat data.account_id as the account ID.
Treat data.status as the declined verification state (rejected).
The account’s status from GET /accounts/{account_id} becomes rejected at the same time, so polling and webhooks agree.
Uploading more documents does not reopen a declined account. Contact Brale if you believe a decline is incorrect.
Your integration should ignore unknown fields.

Subscriptions to the account.verification.* wildcard receive this event automatically. If you subscribed to account.verification.completed by name, add account.verification.rejected to your subscription to be told about declines.

Handling future event types

Brale may add new event types over time. Best practices:

Use GET /accounts/{account_id}/webhooks/event_types to discover supported events.
Branch on event.type.
Acknowledge unknown event types safely.
Ignore unknown fields in data.
Do not assume event ordering.
To automatically receive future events in a family (e.g., new transfer.* or account.* events), subscribe with a namespace wildcard like transfer.* or account.* when you create or update a subscription. Wildcards work for every event family.

Overview

Key concepts

Webhooks

Webhook events

Webhook Events

Event envelope

Managing accounts and event fan-in

`transfer.created`

`transfer.completed`

`transfer.failed`

Returned outbound wires

`payment.completed`

`transfer.canceled`

`account.verification.documents_required`

`account.verification.completed`

`account.verification.rejected`

Handling future event types

​Webhook Events

​Event envelope

​Managing accounts and event fan-in

​transfer.created

​transfer.completed

​transfer.failed

​Returned outbound wires

​payment.completed

​transfer.canceled

​account.verification.documents_required

​account.verification.completed

​account.verification.rejected

​Handling future event types

Webhook Events

Event envelope

Managing accounts and event fan-in

`transfer.created`

`transfer.completed`

`transfer.failed`

Returned outbound wires

`payment.completed`

`transfer.canceled`

`account.verification.documents_required`

`account.verification.completed`

`account.verification.rejected`

Handling future event types