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, address.created, address.ready, transfer.created, transfer.failed, transfer.refunding, and transfer.refunded, 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 "transfer.refunding":
  case "transfer.refunded":
    await handleRefundEvent(event);
    break;
  case "payment.completed":
    await handlePaymentCompleted(event.data);
    break;
  case "address.created":
  case "address.ready":
    await handleAddressEvent(event);
    break;
  default:
    // Unknown future event type.
    // Store and acknowledge safely.
    break;
}

`transfer.created`

Emitted when a Brale transfer is created. Example:

{
  "id": "36KkY9pF34Qy6nB3Wwd25rq4f5z",
  "type": "transfer.created",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "36Kr3QA7YeEEBY3ABp3e2zS8iq9",
    "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": "36Ky7AjzQHb6BAEcn6zJ4A3DdvH",
  "type": "transfer.completed",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "36KyrNktBXtnjfObINf5AjxvUlK",
    "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 and outbound ACH payouts, transfer.completed is not a guarantee that the payout cannot be returned later. If the bank returns the payout, 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": "36KsiC47wqaMl9Xvq2ZG4MzAOUQ",
  "type": "transfer.failed",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "36KklImCvBPt4R5YhuIG43KIjFA",
    "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 event. If Brale later refunds the payout, it reports the refund with the separate refund events transfer.refunding and transfer.refunded. 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": "36KHQsiJoUGm1YtmaD7v3dNi8Lf",
  "type": "transfer.failed",
  "created": "2026-10-06T18:30:05.000000Z",
  "data": {
    "id": "36KppWTv5aspzhU8QrTzhJqmHUo",
    "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. Not every failed or returned payout is refunded. Use transfer.refunding and transfer.refunded to track a refund.
Do not assume event ordering. Retrieve the latest transfer when you need to reconcile its current state.

Refund events

Brale reports the refund lifecycle with two events in the transfer family. They are separate from transfer.failed:

Event	What it tells you	What it does not tell you
`transfer.failed`	The payout failed or was returned.	That a refund has started or completed.
`transfer.refunding`	The refund process has started.	That the refund is complete.
`transfer.refunded`	The refund has completed.	—

Refund events apply to a redemption (stablecoin to fiat payout) whose payout was returned or canceled and then refunded. They use the same transfer as the original payout, so data.id matches the data.id you received on transfer.failed or transfer.canceled. A refunded payout produces this sequence: transfer.failed (or transfer.canceled) → transfer.refunding → transfer.refunded After the refund starts, the transfer’s status is refunding and then refunded. Brale does not send transfer.completed, transfer.failed, or transfer.canceled for the transfer after that point. A failed or returned payout is not automatically followed by a refund. Do not wait for transfer.refunding or transfer.refunded after every transfer.failed. Subscriptions that use the transfer.* wildcard already receive both refund events. Subscriptions that list event types by name receive them only after you add transfer.refunding and transfer.refunded. See Subscribe to refund events.

`transfer.refunding`

Emitted when the refund process starts. Notes: Example (illustrative):

{
  "id": "36KppWTv5aspzhU8QrTzhJqmHUo",
  "type": "transfer.refunding",
  "created": "2026-10-07T15:00:00.000000Z",
  "data": {
    "id": "36KppWTv5aspzhU8QrTzhJqmHUo",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "refunding",
    "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"
      }
    }
  }
}

Notes:

Treat this event as “refund in progress.” It does not confirm that the refund is complete or that refunded funds are available.
Do not credit your end user’s balance as final based on this event alone. Wait for transfer.refunded.
data.status is always refunding on this event. Brale still delivers transfer.refunding if the refund completes before the event is sent, so the transfer’s current status can already be refunded.
created is the time the refund started.

`transfer.refunded`

Emitted when the refund completes. Notes: Example (illustrative):

{
  "id": "36KppWTv5aspzhU8QrTzhJqmHUo",
  "type": "transfer.refunded",
  "created": "2026-10-07T15:05:00.000000Z",
  "data": {
    "id": "36KppWTv5aspzhU8QrTzhJqmHUo",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "status": "refunded",
    "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"
      }
    }
  }
}

Notes:

Treat this event as confirmation that the refund has completed.
data.status is refunded. created is the time the refund completed.
Delivery order is not guaranteed. You can receive transfer.refunded before transfer.refunding, or without having processed transfer.refunding.

Handle refund events

Both refund events carry the transfer resource in data:

Field	Description
`data.id`	Transfer ID of the original redemption.
`data.account_id`	Account the transfer belongs to.
`data.status`	`refunding` or `refunded`.
`data.amount`	Transfer amount (`value`, `currency`).
`data.source`, `data.destination`	Transfer legs, when available.
`data.failure`	The original payout failure, in the same shape as the transfer `failure` field. Can be `null`.

Ignore unknown fields in data. Retrieve the latest transfer when you need its current state.

async function handleRefundEvent(event) {
  // Signature already verified against the raw request body.

  // Process idempotently: skip events you have already handled.
  // Key on id and type. Both refund events for a transfer share the same id.
  if (await alreadyProcessed(event.id, event.type)) return;

  if (event.type === "transfer.refunding") {
    // Refund started. Do not treat it as complete.
    // Do not overwrite a refund you already recorded as complete.
    await markRefundInProgressUnlessComplete(event);
  } else if (event.type === "transfer.refunded") {
    // Refund completed.
    await markRefundComplete(event);
  }

  await recordProcessed(event.id, event.type);
}

How to handle them:

Verify the signature before you process the event.
Deduplicate on the event id and type together. Brale can deliver the same event more than once, and transfer.refunding and transfer.refunded for the same transfer share the same id.
Do not assume delivery order. Never move a refund you recorded as complete back to in progress.
Retrieve the latest transfer to reconcile when events arrive out of order or you are unsure of the current state.

`payment.completed`

Emitted when a payment reaches complete status. Example:

{
  "id": "36KZe95b9eGe0vRBbgi09qynDAk",
  "type": "payment.completed",
  "created": "2026-04-28T21:30:00.000000Z",
  "data": {
    "id": "36KY8ISwYDFHL3tVTNYTHPzpppp",
    "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.
data.id is a payment ID. It is not a Transfer ID. Brale creates a separate Transfer for Automation deposits.
payment.completed means Brale received the fiat payment. It does not mean the stablecoin mint was delivered. Use transfer.completed or the Transfer’s status for that.
data.type identifies the payment rail. The example shows a wire. For FedNow deposits, do not hard-code an expected data.type value. Correlate with the Transfer instead.
To find the Transfer for an Automation deposit, list Transfers with automation_id and transfer_type (for example, transfer_type=fednow_credit), then match data.account_id, the amount, and source.payment_details.received_at. See Receive FedNow deposits.
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": "36K6uEp3c4dsa7lC360A9y6YnD1",
  "type": "transfer.canceled",
  "created": "2026-04-29T23:30:00.000000Z",
  "data": {
    "id": "36K4TdDo9EgZmCnu77Svtuuj596",
    "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.

Address events

Brale reports new addresses with two events in the address family. Both cover wallets (internal custodial wallets and external wallets) and external bank accounts, including bank accounts linked through Plaid. Subscribe to both with address.*.

Event	When it fires
`address.created`	A wallet or bank account is added to the account. A custodial wallet that is still `pending` triggers this event.
`address.ready`	The wallet or bank account reaches `active` status and can be used as a transfer source or destination.

An address that is created already active produces both events. A custodial wallet created as pending produces address.created first, then address.ready when it becomes active. See Address lifecycle.

`address.created`

Emitted when a wallet or bank account is added to an account. Example (wallet, illustrative):

{
  "id": "2VZvtmVc2j3gQ80CTlcuQXbGrwC",
  "type": "address.created",
  "created": "2026-10-22T18:00:00.000000Z",
  "data": {
    "id": "2VZvtmVc2j3gQ80CTlcuQXbGrwC",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "kind": "wallet",
    "status": "pending",
    "type": "internal",
    "ownership": "self-owned",
    "name": "Treasury Wallet",
    "transfer_types": ["spark"],
    "address": null,
    "account_number": null,
    "routing_number": null,
    "account_type": null
  }
}

Notes:

The event id and data.id are both the address ID.
created is the time the address was added.
data.status is the address status when Brale builds the event: pending, active, archived, or disabled. A delayed delivery can report a status other than the one the address had when it was added.
Do not use the address in transfers based on this event alone. Wait for address.ready or check that data.status is active.

`address.ready`

Emitted when a wallet or bank account reaches active status and can be used in transfers. Example (bank account, illustrative):

{
  "id": "2VZw1Kq9YdPz3hL0mN5sR8tUvXa:ready",
  "type": "address.ready",
  "created": "2026-10-22T18:05:00.000000Z",
  "data": {
    "id": "2VZw1Kq9YdPz3hL0mN5sR8tUvXa",
    "account_id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "kind": "fiat_account",
    "status": "active",
    "type": "external",
    "ownership": "customer-owned",
    "name": "Chase Bank",
    "transfer_types": ["ach_credit", "wire"],
    "address": null,
    "account_number": "****1234",
    "routing_number": "021000021",
    "account_type": "checking"
  }
}

Notes:

The event id is the address ID with a :ready suffix, so it never matches the address.created event id for the same address. data.id is the address ID without the suffix.
created is the time the address was last updated.
data.status is always active on this event.

Address event payload

Both address events carry the same data object. Every field is always present.

Field	Type	Description
`data.id`	string	Address ID. Use it with the Addresses API and as a transfer `address_id`.
`data.account_id`	string	Account the address belongs to.
`data.kind`	string	`wallet` for an onchain wallet or `fiat_account` for a bank account.
`data.status`	string	`pending`, `active`, `archived`, or `disabled`.
`data.type`	string	`internal` for a custodial wallet or `external` for an external wallet or bank account.
`data.ownership`	string	`self-owned` or `customer-owned`.
`data.name`	string or null	Address name.
`data.transfer_types`	array of strings or null	Transfer types the address supports, using the same values as the Addresses API. `null` for a bank account with no transfer types configured yet.
`data.address`	string or null	Onchain address for a wallet. `null` for bank accounts, and `null` for a custodial wallet that is still `pending`.
`data.account_number`	string or null	Masked bank account number (for example, `****1234`). `null` for wallets.
`data.routing_number`	string or null	Bank routing number. `null` for wallets.
`data.account_type`	string or null	`checking` or `savings`. `null` for wallets.

Ignore unknown fields in data. Retrieve the address with the Addresses API when you need its current state.

`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.*, address.*, 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

Event envelope

Managing accounts and event fan-in

`transfer.created`

`transfer.completed`

`transfer.failed`

Returned outbound wires

Refund events

`transfer.refunding`

`transfer.refunded`

Handle refund events

`payment.completed`

`transfer.canceled`

Address events

`address.created`

`address.ready`

Address event payload

`account.verification.documents_required`

`account.verification.completed`

`account.verification.rejected`

Handling future event types

​Event envelope

​Managing accounts and event fan-in

​transfer.created

​transfer.completed

​transfer.failed

​Returned outbound wires

​Refund events

​transfer.refunding

​transfer.refunded

​Handle refund events

​payment.completed

​transfer.canceled

​Address events

​address.created

​address.ready

​Address event payload

​account.verification.documents_required

​account.verification.completed

​account.verification.rejected

​Handling future event types

Event envelope

Managing accounts and event fan-in

`transfer.created`

`transfer.completed`

`transfer.failed`

Returned outbound wires

Refund events

`transfer.refunding`

`transfer.refunded`

Handle refund events

`payment.completed`

`transfer.canceled`

Address events

`address.created`

`address.ready`

Address event payload

`account.verification.documents_required`

`account.verification.completed`

`account.verification.rejected`

Handling future event types