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.
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 or other rail/provider failures). For ACH-specific return details, inspect data.failure.ach_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.

`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.

`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`

`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

​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`

`payment.completed`

`transfer.canceled`

`account.verification.documents_required`

`account.verification.completed`

`account.verification.rejected`

Handling future event types