Download OpenAPI specification:Download
Brex uses webhooks to send real-time notifications when events happen in the accounts that you manage. Use webhook subscriptions to subscribe to different webhook events.
OAuth2 security scheme
| Security Scheme Type | OAuth2 |
|---|---|
| clientCredentials OAuth Flow | Token URL: https://accounts.brex.com/oauth2/v1/token Scopes:
|
| authorizationCode OAuth Flow | Authorization URL: https://accounts.brex.com/oauth2/v1/auth Token URL: https://accounts.brex.com/oauth2/v1/token Scopes:
|
List the webhooks you have registered
listSubscription 200 response
Bad request
Unauthorized
Forbidden
Internal server error
curl -i -X GET \ https://platform.brexapis.com/v1/webhooks \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
{- "next_cursor": "string",
- "items": [
- {
- "id": "string",
- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
], - "status": "ACTIVE"
}
]
}Register an endpoint to start receiving selected webhook events
| url required | string |
| event_types required | Array of strings (WebhookEventType) The Brex API sends webhooks for the events listed below. For more details, see the webhook guide and webhook events API reference. |
createSubscription 200 response
Bad request
Unauthorized
Forbidden
Internal server error
{- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
]
}{- "id": "string",
- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
], - "status": "ACTIVE"
}This endpoint returns a set of webhook signing secrets used to validate the webhook. Usually only one key will be returned in the response. After key rotation, this endpoint will return two keys: the new key, and the key that will be revoked soon. There will also be two signatures in the 'Webhook-Signature' request header. Your application should use all keys available to validate the webhook request. If validation passes for any of the keys returned, the webhook payload is valid.
listSecrets 200 response
Bad request
Unauthorized
Forbidden
Internal server error
curl -i -X GET \ https://platform.brexapis.com/v1/webhooks/secrets \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
[- {
- "secret": "string",
- "status": "ACTIVE"
}
]Get details of a webhook
getSubscriptionById 200 response
Bad request
Unauthorized
Forbidden
Internal server error
curl -i -X GET \ 'https://platform.brexapis.com/v1/webhooks/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
{- "id": "string",
- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
], - "status": "ACTIVE"
}Update a webhook. You can update the endpoint url, event types that the endpoint receives, or temporarily deactivate the webhook.
updateSubscription 200 response
Bad request
Unauthorized
Forbidden
Internal server error
{- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
], - "status": "ACTIVE"
}{- "id": "string",
- "url": "string",
- "event_types": [
- "REFERRAL_CREATED"
], - "status": "ACTIVE"
}Unregister a webhook if you want to stop receiving webhook events
deleteSubscription 200 response
Bad request
Unauthorized
Forbidden
Internal server error
curl -i -X DELETE \ 'https://platform.brexapis.com/v1/webhooks/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Expense Payment Events. Transaction activity for expenses made on Brex Card.
Account must be on Brex Empower to receive these events. Webhook subscription must be registered using a token from a user with Card Admin role.
expenses.card.readonly) | event_type required | string (WebhookEventType) |
| expense_id required | string |
| payment_status required | string (ExpensePaymentStatus)
|
| payment_type required | string (ExpensePaymentType)
|
| company_id | string This is the |
object or null 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. | |
| payment_description | string The name of the card acceptor. |
Return this code if the callback was received and processed successfully
{- "event_type": "EXPENSE_PAYMENT_UPDATED",
- "expense_id": "string",
- "payment_status": "PENDING",
- "payment_type": "PURCHASE",
- "company_id": "string",
- "amount": {
- "amount": 0,
- "currency": "string"
}, - "payment_description": "string"
}Referral Events. Reference the Onboarding API for event details.
Return this code if the callback was received and processed successfully
{- "event_type": "REFERRAL_ACTIVATED",
- "referral_id": "string"
}Transfer Events for both incoming and outgoing Brex Cash transactions. Reference the Payments API for event details.
transfers.readonlytransfers) | event_type required | string (WebhookEventType) |
| transfer_id required | string |
| payment_type required | string (PaymentType) Only ACH, DOMESTIC_WIRE, CHEQUE, INTERNATIONAL_WIRE and BOOK_TRANSFER details can be retrieved from the Payments API. |
| return_for_id | string or null The original transaction ID that is returned when the payment type is ACH_RETURN, WIRE_RETURN and CHEQUE_RETURN. |
| company_id | string This is the |
Return this code if the callback was received and processed successfully
{- "event_type": "TRANSFER_FAILED",
- "transfer_id": "string",
- "payment_type": "ACH",
- "return_for_id": "string",
- "company_id": "string"
}