asyncapi: '2.6.0' id: 'urn:com:brex:webhooks' info: title: Brex Webhooks API version: '0.1' description: > AsyncAPI 2.6 description of the Brex Webhooks surface. Brex uses webhooks to deliver real-time notifications when events happen in the accounts that you manage. Subscribers register an HTTPS callback URL via the Webhooks API (Subscriptions endpoints) and select one or more event types from the `WebhookEventType` enum. Brex POSTs JSON payloads to the registered URL when matching events occur; subscribers respond with a 200 status code to confirm receipt. Incoming requests can be validated using the secrets returned from `GET /v1/webhooks/secrets`. contact: name: Brex Developer Support url: https://developer.brex.com/ email: developer-support@brex.com license: name: Proprietary x-generated-from: https://developer.brex.com/openapi/webhooks_api/ x-source-bundle: https://developer.brex.com/_bundle/openapi/webhooks_api.yaml x-generated-by: claude-crawl-2026-05-30 x-api-evangelist: aid: brex:brex-webhooks note: > Only the event types and payload schemas that are explicitly documented in the Brex Webhooks OpenAPI bundle are modeled here. The WebhookEventType enum contains additional values used by the Brex Embedded program (EMBEDDED_* and PARTNERSHIP_INTEGRATION_CONNECTION_UPDATED) for which Brex does not publish public payload schemas; those values are kept in the enum but not bound to dedicated channels. defaultContentType: application/json servers: subscriber: url: '{webhookUrl}' protocol: https description: > The HTTPS endpoint that the subscriber registers with Brex via `POST /v1/webhooks`. Brex delivers webhook events by sending HTTPS POST requests to this URL. Must be a valid HTTPS URL. variables: webhookUrl: default: https://example.com/webhook description: The subscriber-controlled HTTPS callback URL. channels: accountingRecordReadyForExport: description: >- Fired when a list of accounting records is ready for export. Sent to the subscriber callback URL via HTTPS POST. publish: operationId: onAccountingRecordReadyForExport summary: Accounting Record Ready For Export Event description: A list of accounting records are ready for export. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/AccountingRecordReadyForExport' expensePaymentUpdated: description: >- Fired when an expense payment changes status on a Brex Card. Subscription must be registered with a user with the CARD_ADMIN role. publish: operationId: onExpensePaymentUpdated summary: Expense Payment Updated Event description: Expense activity on Brex Cards. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/ExpensePaymentUpdated' referralActivated: description: Fired when a user signs up with the referral link. publish: operationId: onReferralActivated summary: Referral Activated Event description: A referral was activated. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/ReferralActivated' referralApplicationStatusChanged: description: Fired when the application status of a referral changes. publish: operationId: onReferralApplicationStatusChanged summary: Referral Application Status Changed Event description: A referral's application status changed. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/ReferralApplicationStatusChanged' referralCreated: description: Fired when a referral is created. publish: operationId: onReferralCreated summary: Referral Created Event description: A referral was created. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/ReferralCreated' transferFailed: description: >- Fired when a transfer fails. Covers incoming and outgoing Brex Cash transactions and supports ACH, DOMESTIC_WIRE, CHEQUE, INTERNATIONAL_WIRE, BOOK_TRANSFER, STABLECOIN, and the ACH_RETURN / WIRE_RETURN / CHEQUE_RETURN return types. publish: operationId: onTransferFailed summary: Transfer Failed Event description: >- Transfer failed events for both incoming and outgoing Brex Cash transactions. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/TransferFailed' transferProcessed: description: >- Fired when a transfer is processed. Covers incoming and outgoing Brex Cash transactions across the same payment types as `transferFailed`. publish: operationId: onTransferProcessed summary: Transfer Processed Event description: >- Transfer processed events for both incoming and outgoing Brex Cash transactions. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/TransferProcessed' userUpdated: description: >- Fired when a Brex user is updated. The payload lists which user attributes changed (STATUS, MANAGER_ID, DEPARTMENT_ID, LOCATION_ID). publish: operationId: onUserUpdated summary: User Updated Event description: Updates on Brex users. bindings: http: type: request method: POST bindingVersion: '0.3.0' message: $ref: '#/components/messages/UserUpdated' components: messages: AccountingRecordReadyForExport: name: AccountingRecordReadyForExport title: Accounting Record Ready For Export summary: A list of accounting records are ready for export. contentType: application/json payload: $ref: '#/components/schemas/AccountingRecordReadyForExport' ExpensePaymentUpdated: name: ExpensePaymentUpdated title: Expense Payment Updated summary: An expense payment changed status on a Brex Card. contentType: application/json payload: $ref: '#/components/schemas/ExpensePaymentUpdated' ReferralActivated: name: ReferralActivated title: Referral Activated summary: A user signed up with a referral link. contentType: application/json payload: $ref: '#/components/schemas/ReferralActivated' ReferralApplicationStatusChanged: name: ReferralApplicationStatusChanged title: Referral Application Status Changed summary: A referral's application status changed. contentType: application/json payload: $ref: '#/components/schemas/ReferralApplicationStatusChanged' ReferralCreated: name: ReferralCreated title: Referral Created summary: A referral was created. contentType: application/json payload: $ref: '#/components/schemas/ReferralCreated' TransferFailed: name: TransferFailed title: Transfer Failed summary: A Brex Cash transfer failed. contentType: application/json payload: $ref: '#/components/schemas/TransferFailed' TransferProcessed: name: TransferProcessed title: Transfer Processed summary: A Brex Cash transfer was processed. contentType: application/json payload: $ref: '#/components/schemas/TransferProcessed' UserUpdated: name: UserUpdated title: User Updated summary: A Brex user was updated. contentType: application/json payload: $ref: '#/components/schemas/UserUpdated' schemas: WebhookEventType: type: string description: >- The full set of webhook event type identifiers recognized by Brex. The Brex Embedded program (EMBEDDED_* and PARTNERSHIP_INTEGRATION_CONNECTION_UPDATED) extends this enum but does not publish public payload schemas. enum: - REFERRAL_CREATED - REFERRAL_ACTIVATED - REFERRAL_APPLICATION_STATUS_CHANGED - TRANSFER_PROCESSED - TRANSFER_FAILED - EXPENSE_PAYMENT_UPDATED - USER_UPDATED - EMBEDDED_CARD_TRANSACTION_UPDATED - EMBEDDED_CARD_UPDATED - EMBEDDED_ACCOUNT_UPDATED - EMBEDDED_CARD_SHIPPING_UPDATED - EMBEDDED_DISPUTE_UPDATED - PARTNERSHIP_INTEGRATION_CONNECTION_UPDATED - EMBEDDED_CARD_AUTHORIZATION - EMBEDDED_FRAUD_ALERT - EMBEDDED_BILLING_GROUP_UPDATED - EMBEDDED_LEGAL_ENTITY_UPDATED - EMBEDDED_BILLING_STATEMENT_UPDATED - EMBEDDED_USER_STATUS_UPDATED - ACCOUNTING_RECORD_READY_FOR_EXPORT ApplicationStatus: type: string description: > Application status of a product. `NO_ACCOUNT` - There is no active application, and the product account is not provisioned. `ACTIVE` - The application is approved, and the product account is provisioned. `NOT_SUBMITTED` - The application is started but not yet submitted. `INFORMATION_PENDING` - The application is submitted and additional information is requested. `MANUAL_REVIEW` - The application is under manual review. `PROCESSING` - The application is submitted and is under review. `REJECTED` - The application is rejected. `CLOSED` - The product account is closed. enum: - NO_ACCOUNT - ACTIVE - NOT_SUBMITTED - INFORMATION_PENDING - MANUAL_REVIEW - PROCESSING - REJECTED - CLOSED ProductApplication: type: object description: The product application details for the referral. required: - cash properties: cash: $ref: '#/components/schemas/ApplicationStatus' ExpensePaymentStatus: type: string description: >- `PENDING`: The transaction is yet to be captured. It may be approved, yet to be approved, or yet to be declined. `DECLINED`: The transaction was declined. enum: - PENDING - DECLINED ExpensePaymentType: type: string description: >- `PURCHASE`: A pending transaction for making a purchase. `REFUND`: A pending transaction for a refund. `WITHDRAWAL`: A pending transaction for a withdrawal. `DECLINED`: A pending transaction that was declined and will not be completed. enum: - PURCHASE - REFUND - WITHDRAWAL - DECLINED PaymentType: type: string description: >- Only ACH, DOMESTIC_WIRE, CHEQUE, INTERNATIONAL_WIRE, BOOK_TRANSFER, and STABLECOIN details can be retrieved from the Payments API. enum: - ACH - DOMESTIC_WIRE - CHEQUE - INTERNATIONAL_WIRE - BOOK_TRANSFER - STABLECOIN - ACH_RETURN - WIRE_RETURN - CHEQUE_RETURN PaymentStatusReason: type: string description: The reason for the payment's status. enum: - OTHER - APPROVED - EXCEEDED_BUDGET_LIMIT - BUDGET_EXPIRED - NO_BUDGET - BUDGET_NOT_YET_STARTED - BUDGET_CATEGORY_RESTRICTION - BUDGET_MERCHANT_RESTRICTION - SUSPECTED_FRAUD - EXCEEDED_GLOBAL_LIMIT - EXCEEDED_USER_LIMIT - EXCEEDED_CARD_LIMIT - INVALID_EXPIRATION_DATE - CARD_NOT_ACTIVE - INVALID_CARD_CREDENTIALS - INVALID_BILLING_ADDRESS - CARD_SUSPENDED - CARD_TERMINATED - CARD_EXPIRED - MCC_BLOCKED - USER_SUSPENDED - INVALID_PIN - INVALID_CVV - EXCEEDED_PIN_ATTEMPTS - INSIDE_SANCTIONED_COUNTRY - SOFT_EXPIRATION - TRANSFERRED_CARD_NEW_MERCHANT - EXCEEDED_ANCESTOR_BUDGET_LIMIT - EXCEEDED_BUDGET_TRANSACTION_LIMIT - TOS_BLOCKED - COMPLIANCE_BLOCKED UserAttributes: type: string description: A user attribute that can change and trigger USER_UPDATED. enum: - STATUS - MANAGER_ID - DEPARTMENT_ID - LOCATION_ID Money: type: object description: > Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700. required: - amount properties: amount: type: integer format: int64 description: >- The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. example: 700 currency: type: string description: The type of currency, in ISO 4217 format. default: USD example: USD Merchant: type: object required: - country - mcc - raw_descriptor properties: raw_descriptor: type: string description: Merchant descriptor, it can be the merchant name. mcc: type: string description: >- A four-digit number listed in ISO 18245 for retail financial services, e.g. 4121 for Taxicabs and Rideshares. country: type: string description: Merchant's country, in ISO 3166-1 alpha-3 format. AccountingRecordReadyForExport: type: object description: A list of accounting records are ready for export. required: - accountingRecordIds - companyId - event_type properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: ACCOUNTING_RECORD_READY_FOR_EXPORT accountingRecordIds: type: array description: List of accounting record IDs ready for export. items: type: string companyId: type: string description: >- The `id` returned by the Get Company endpoint of the Team API. Use it to determine which access token to use when fetching details. ExpensePaymentUpdated: type: object description: >- Sent when an expense payment changes status. Subscription must be registered with a user with the CARD_ADMIN role. required: - card_id - company_id - event_type - expense_id - merchant - payment_description - payment_status - payment_status_reason - payment_type - version properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: EXPENSE_PAYMENT_UPDATED expense_id: type: string description: Unique ID associated with the expense. payment_status: $ref: '#/components/schemas/ExpensePaymentStatus' payment_type: $ref: '#/components/schemas/ExpensePaymentType' company_id: type: string description: >- The `id` returned by the Get Company endpoint of the Team API. Use it to determine which access token to use when fetching details. purchased_at: type: string format: date-time description: The time the purchase was made. amount: allOf: - $ref: '#/components/schemas/Money' description: Succeeded by the billing_amount field. deprecated: true original_amount: allOf: - $ref: '#/components/schemas/Money' description: >- The original amount of the expense is the amount that the employee submitted or incurred for reimbursements or card spends. billing_amount: allOf: - $ref: '#/components/schemas/Money' description: >- The billing amount of the expense is the amount that the entity is charged, on the entity's currency, for reimbursements or card spends. payment_description: type: string description: Succeeded by the merchant::raw_descriptor field. deprecated: true card_id: type: string description: The ID of the card that is associated with the expense. merchant: allOf: - $ref: '#/components/schemas/Merchant' description: The merchant associated with the expense. payment_status_reason: $ref: '#/components/schemas/PaymentStatusReason' payment_authorization_code: type: string description: The authorization code of the associated card expense. version: type: integer format: int32 minimum: 1 description: >- Version of this expense. This value starts at 1 and is incremented by 1 with every update. example: 1 ReferralActivated: type: object description: Sent when a user signs up with the referral link. required: - event_type - referral_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: REFERRAL_ACTIVATED referral_id: type: string description: The referral ID. ReferralApplicationStatusChanged: type: object description: Sent when the application status is changed for a referral. required: - application - event_type - referral_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: REFERRAL_APPLICATION_STATUS_CHANGED referral_id: type: string description: The referral ID. application: $ref: '#/components/schemas/ProductApplication' ReferralCreated: type: object description: Sent when a referral is created. required: - event_type - referral_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: REFERRAL_CREATED referral_id: type: string description: The referral ID. TransferFailed: type: object description: Sent when a transfer failed. required: - company_id - event_type - payment_type - transfer_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: TRANSFER_FAILED transfer_id: type: string description: The transfer ID. payment_type: $ref: '#/components/schemas/PaymentType' return_for_id: type: string description: >- The original transaction ID that is returned when the payment type is ACH_RETURN, WIRE_RETURN, or CHEQUE_RETURN. company_id: type: string description: >- The `id` returned by the Get Company endpoint of the Team API. Use it to determine which access token to use when fetching details. TransferProcessed: type: object description: Sent when a transfer is processed. required: - company_id - event_type - payment_type - transfer_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: TRANSFER_PROCESSED transfer_id: type: string description: The transfer ID. payment_type: $ref: '#/components/schemas/PaymentType' return_for_id: type: string description: >- The original transaction ID that is returned when the payment type is ACH_RETURN, WIRE_RETURN, or CHEQUE_RETURN. company_id: type: string description: >- The `id` returned by the Get Company endpoint of the Team API. Use it to determine which access token to use when fetching details. UserUpdated: type: object description: Sent when a user is updated. required: - company_id - event_type - updated_attributes - user_id properties: event_type: allOf: - $ref: '#/components/schemas/WebhookEventType' example: USER_UPDATED user_id: type: string description: The ID of the user that was updated. company_id: type: string description: >- The `id` returned by the Get Company endpoint of the Team API. Use it to determine which access token to use when fetching details. updated_attributes: type: array description: The set of user attributes that changed in this update. items: $ref: '#/components/schemas/UserAttributes'