Home Original page

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.

Staging (Note: This is not a sandbox. It will not work with customer tokens.)

https://api-staging.brex.com

Manage webhook subscriptions.

List Webhooks

Request

List the webhooks you have registered

Query

limitinteger or null(int32)

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

Responses

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"

{

  
"next_cursor": "string",

  
"items": 
[

    
{
 … 
}

  
]


}

Was this helpful?

Register Webhook

Request

Register an endpoint to start receiving selected webhook events

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

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"

{

  
"id": "wsub_123",

  
"group_id": "wg_123",

  
"url": "https://example.com/webhook",

  
"event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",

  
"status": "ACTIVE"
}

Was this helpful?

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.

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

Responses

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.

]

[

  
{

    
"secret": "whsec_123",

    
"status": "ACTIVE"
  
}


]

Was this helpful?

Get Webhook

Request

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

Responses

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"

{

  
"id": "wsub_123",

  
"group_id": "wg_123",

  
"url": "https://example.com/webhook",

  
"event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",

  
"status": "ACTIVE"
}

Was this helpful?

Update Webhook

Request

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

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

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"

{

  
"id": "wsub_123",

  
"group_id": "wg_123",

  
"url": "https://example.com/webhook",

  
"event_types": "[\"EXPENSE_PAYMENT_UPDATED\"]",

  
"status": "ACTIVE"
}

Was this helpful?

Unregister Webhook

Request

Unregister a webhook if you want to stop receiving webhook events

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

Responses

Was this helpful?

Webhook Groups

Schemas

Webhook Events