Skip to content
APIs/
/Webhook Subscriptions

Webhooks API (0.1)

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.

Download OpenAPI description
webhooks_api.json
webhooks_api.yaml
Overview
URL
https://brex.com
Admin
developer-support@brex.com
Languages
Servers
Production
https://api.brex.com
Staging (Note: This is not a sandbox. It will not work with customer tokens.)
https://api-staging.brex.com

Webhook Subscriptions

Manage webhook subscriptions.

Operations

List Webhooks

Request

List the webhooks you have registered

Security
OAuth2
Query
cursorstring or null
limitinteger or null(int32)
curl -i -X GET \
  https://api.brex.com/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
next_cursorstring or null
itemsArray of objects(Webhook Subscription)required
items[].​idstringnon-emptyrequired

ID of the webhook subscription.

Example: "wsub_123"
items[].​group_idstring or null

ID of the webhook group to which this subscription applies, if any.

Example: "wg_123"
items[].​urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
items[].​event_typesArray of strings(WebhookEventType)required

List of event types that this webhook subscription listens to.

Items 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"
Example: "[\"EXPENSE_PAYMENT_UPDATED\"]"
items[].​statusstringrequired

The status of a webhook subscription.

Enum ValueDescription
ACTIVE

The webhook subscription is active and the associated URL will receive the subscribed event types.

INACTIVE

The webhook subscription is no longer active.

Example: "ACTIVE"
Response
application/json
{
  "next_cursor": "string",
  "items": [
    { … }
  ]
}

Register Webhook

Request

Register an endpoint to start receiving selected webhook events

Security
OAuth2
Headers
Idempotency-Keystringrequired
Bodyapplication/jsonrequired
urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
group_idstring or null

ID of the webhook group to which this subscription applies, if any. This is only available for partners.

Example: "wg_123"
event_typesArray of strings(WebhookEventType)non-emptyrequired

A list of the webhook event types this subscription will listen to.

Items 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"
curl -i -X POST \
  https://api.brex.com/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "url": "https://example.com/webhook",
    "group_id": "wg_123",
    "event_types": [
      "REFERRAL_CREATED"
    ]
  }'

Responses

Success

Bodyapplication/json
idstringnon-emptyrequired

ID of the webhook subscription.

Example: "wsub_123"
group_idstring or null

ID of the webhook group to which this subscription applies, if any.

Example: "wg_123"
urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
event_typesArray of strings(WebhookEventType)required

List of event types that this webhook subscription listens to.

Items 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"
Example: "[\"EXPENSE_PAYMENT_UPDATED\"]"
statusstringrequired

The status of a webhook subscription.

Enum ValueDescription
ACTIVE

The webhook subscription is active and the associated URL will receive the subscribed event types.

INACTIVE

The webhook subscription is no longer active.

Example: "ACTIVE"
Response
application/json
{
  "id": "wsub_123",
  "group_id": "wg_123",
  "url": "https://example.com/webhook",
  "event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",
  "status": "ACTIVE"
}

List Webhook Secrets

Request

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.

Security
OAuth2
curl -i -X GET \
  https://api.brex.com/v1/webhooks/secrets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/jsonArray [
secretstringnon-emptyrequired

The payload of the secret to be used for webhook validation.

Example: "whsec_123"
statusstringrequired

The status of a webhook secret.

Enum ValueDescription
ACTIVE

The webhook secret is active and can be used to validate webhooks from Brex.

PENDING_REVOKE

The webhook secret is still active, but it will soon be revoked. This may happen during key rotations.

REVOKED

The webhook secret is no longer active. It cannot be used to validate webhooks from Brex.

]
Response
application/json
[
  {
    "secret": "whsec_123",
    "status": "ACTIVE"
  }
]

Get Webhook

Request

Get details of a webhook

Security
OAuth2
Path
idstringrequired
curl -i -X GET \
  'https://api.brex.com/v1/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
idstringnon-emptyrequired

ID of the webhook subscription.

Example: "wsub_123"
group_idstring or null

ID of the webhook group to which this subscription applies, if any.

Example: "wg_123"
urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
event_typesArray of strings(WebhookEventType)required

List of event types that this webhook subscription listens to.

Items 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"
Example: "[\"EXPENSE_PAYMENT_UPDATED\"]"
statusstringrequired

The status of a webhook subscription.

Enum ValueDescription
ACTIVE

The webhook subscription is active and the associated URL will receive the subscribed event types.

INACTIVE

The webhook subscription is no longer active.

Example: "ACTIVE"
Response
application/json
{
  "id": "wsub_123",
  "group_id": "wg_123",
  "url": "https://example.com/webhook",
  "event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",
  "status": "ACTIVE"
}

Update Webhook

Request

Update a webhook. You can update the endpoint url, event types that the endpoint receives, or temporarily deactivate the webhook.

Security
OAuth2
Path
idstringrequired
Bodyapplication/jsonrequired
urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
group_idstring or null

ID of the webhook group to which this subscription applies, if any. This is only available for partners.

Example: "wg_123"
event_typesArray of strings(WebhookEventType)required

A list of the webhook event types this subscription will listen to.

Items 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"
statusstringrequired

The status of a webhook subscription.

Enum ValueDescription
ACTIVE

The webhook subscription is active and the associated URL will receive the subscribed event types.

INACTIVE

The webhook subscription is no longer active.

Example: "ACTIVE"
curl -i -X PUT \
  'https://api.brex.com/v1/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhook",
    "group_id": "wg_123",
    "event_types": [
      "REFERRAL_CREATED"
    ],
    "status": "ACTIVE"
  }'

Responses

Success

Bodyapplication/json
idstringnon-emptyrequired

ID of the webhook subscription.

Example: "wsub_123"
group_idstring or null

ID of the webhook group to which this subscription applies, if any.

Example: "wg_123"
urlstringrequired

The URL to which webhook events will be sent. Must be a valid HTTPS URL.

Example: "https://example.com/webhook"
event_typesArray of strings(WebhookEventType)required

List of event types that this webhook subscription listens to.

Items 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"
Example: "[\"EXPENSE_PAYMENT_UPDATED\"]"
statusstringrequired

The status of a webhook subscription.

Enum ValueDescription
ACTIVE

The webhook subscription is active and the associated URL will receive the subscribed event types.

INACTIVE

The webhook subscription is no longer active.

Example: "ACTIVE"
Response
application/json
{
  "id": "wsub_123",
  "group_id": "wg_123",
  "url": "https://example.com/webhook",
  "event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",
  "status": "ACTIVE"
}

Unregister Webhook

Request

Unregister a webhook if you want to stop receiving webhook events

Security
OAuth2
Path
idstringrequired
curl -i -X DELETE \
  'https://api.brex.com/v1/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Webhook Groups

Manage webhook groups.

Operations

Schemas

Schemas.

Schemas

Webhook Events

Webhooks
Copyright © Brex 2019–2026. All rights reserved.