Webhooks API (0.1)

Download OpenAPI specification:Download

Admin: developer-access@brex.com URL: https://brex.com

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.

Webhook Subscriptions

Manage webhook subscriptions.

List Webhooks

List the webhooks you have registered

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
Responses
200

listSubscription 200 response

400

Bad request

401

Unauthorized

403

Forbidden

500

Internal server error

get/v1/webhooks
Request samples 
Response samples 
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}
Register Webhook
Register an endpoint to start receiving selected webhook events


SecurityOAuth2 
Request 
header Parameters
Idempotency-Key
required
string
 
Request Body schema: application/json
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.


Items Enum: "REFERRAL_CREATED" "REFERRAL_ACTIVATED" "REFERRAL_APPLICATION_STATUS_CHANGED" "TRANSFER_PROCESSED" "TRANSFER_FAILED" "EXPENSE_PAYMENT_UPDATED" "USER_UPDATED"  
Responses 
200
createSubscription 200 response


400
Bad request


401
Unauthorized


403
Forbidden


500
Internal server error


post/v1/webhooks
Request samples 
application/json
{
  • "url": "string",
  • "event_types": [
    ]
}
Response samples 
application/json
{
  • "id": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "status": "ACTIVE"
}
List Webhook Secrets
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.


SecurityOAuth2 
Responses 
200
listSecrets 200 response


400
Bad request


401
Unauthorized


403
Forbidden


500
Internal server error


get/v1/webhooks/secrets
Request samples 
Response samples 
application/json
[
  • {
    }
]
Get Webhook
Get details of a webhook


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
getSubscriptionById 200 response


400
Bad request


401
Unauthorized


403
Forbidden


500
Internal server error


get/v1/webhooks/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "status": "ACTIVE"
}
Update Webhook
Update a webhook.
You can update the endpoint url, event types that the endpoint receives, or temporarily deactivate the webhook.


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Request Body schema: application/json
url
required
string
 
event_types
required
Array of strings (WebhookEventType) 
Items Enum: "REFERRAL_CREATED" "REFERRAL_ACTIVATED" "REFERRAL_APPLICATION_STATUS_CHANGED" "TRANSFER_PROCESSED" "TRANSFER_FAILED" "EXPENSE_PAYMENT_UPDATED" "USER_UPDATED"  
status
required
string (UpdateWebhookSubscriptionStatus) 
 Enum: "ACTIVE" "INACTIVE"  
Responses 
200
updateSubscription 200 response


400
Bad request


401
Unauthorized


403
Forbidden


500
Internal server error


put/v1/webhooks/{id}
Request samples 
application/json
{
  • "url": "string",
  • "event_types": [
    ],
  • "status": "ACTIVE"
}
Response samples 
application/json
{
  • "id": "string",
  • "url": "string",
  • "event_types": [
    ],
  • "status": "ACTIVE"
}
Unregister Webhook
Unregister a webhook if you want to stop receiving webhook events


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
Responses 
200
deleteSubscription 200 response


400
Bad request


401
Unauthorized


403
Forbidden


500
Internal server error


delete/v1/webhooks/{id}
Request samples 
Webhook Events
Expense Payment EventsWebhook 
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.


SecurityOAuth2 
Request 
Request Body schema: application/json
event_type
required
string (WebhookEventType) 
 
expense_id
required
string
Unique ID associated with the expense.


 
payment_status
required
string (ExpensePaymentStatus) 
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"  
payment_status_reason
required
string (ExpensePaymentStatusReason) 
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"  
payment_type
required
string (ExpensePaymentType) 
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"  
company_id
string
This is the id returned in the Get Company endpoint.
You can use the company_id to determine which access token to use when you get the details from our API endpoints.


 
purchased_at
string <date-time> 
The time the purchase was made.


 
object or null
The original amount of the expense is the amount that the employee submitted or incurred for reimbursements or card spends.


 
object or null
The billing amount of the expense is the amount that the entity is charged, on the entity's currency, for reimbursements or card spends.


 
card_id
string
The ID of the card that is associated with the expense.


 
object or null
The merchant associated with the expense.


 
payment_authorization_code
string
The authorization code of the associated card expense.


 
object or null
 Deprecated 
Succeeded by the billing_amount field.


 
payment_description
string
 Deprecated 
Succeeded by the merchant::raw_descriptor field.


 
Responses 
200
Return this code if the callback was received and processed successfully


Request samples 
application/json
{
  • "event_type": "EXPENSE_PAYMENT_UPDATED",
  • "expense_id": "string",
  • "payment_status": "PENDING",
  • "payment_status_reason": "OTHER",
  • "payment_type": "PURCHASE",
  • "company_id": "string",
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "card_id": "string",
  • "merchant": {
    },
  • "payment_authorization_code": "string",
  • "amount": {
    },
  • "payment_description": "string"
}
Referral EventsWebhook 
Referral Events. Reference the Onboarding API for event details.


SecurityOAuth2 
Request 
Request Body schema: application/json
event_type
required
string (WebhookEventType) 
 
referral_id
required
string
 
Responses 
200
Return this code if the callback was received and processed successfully


Request samples 
application/json
{
  • "event_type": "REFERRAL_ACTIVATED",
  • "referral_id": "string"
}
Transfer EventsWebhook 
Transfer Events for both incoming and outgoing Brex Cash transactions. Reference the Payments API for event details.


SecurityOAuth2 
Request 
Request Body schema: application/json
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.


 Enum: "ACH" "DOMESTIC_WIRE" "CHEQUE" "INTERNATIONAL_WIRE" "BOOK_TRANSFER" "ACH_RETURN" "WIRE_RETURN" "CHEQUE_RETURN"  
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 id returned in the Get Company endpoint.
You can use the company_id to determine which access token to use when you get the details from our API endpoints.


 
Responses 
200
Return this code if the callback was received and processed successfully


Request samples 
application/json
{
  • "event_type": "TRANSFER_FAILED",
  • "transfer_id": "string",
  • "payment_type": "ACH",
  • "return_for_id": "string",
  • "company_id": "string"
}
User Updated EventsWebhook 
User Updated Events. All accounts can receive user status update while only accounts on Brex Empower can receive non-user-status updates.


SecurityOAuth2 
Request 
Request Body schema: application/json
event_type
required
string (WebhookEventType) 
 
user_id
required
string
 
company_id
required
string
 
updated_attributes
required
Array of strings (UserAttributes) 
Items Enum: "STATUS" "MANAGER_ID" "DEPARTMENT_ID" "LOCATION_ID"  
Responses 
200
Return this code if the callback was received and processed successfully


Request samples 
application/json
{
  • "event_type": "USER_UPDATED",
  • "user_id": "string",
  • "company_id": "string",
  • "updated_attributes": [
    ]
}
Copyright © Brex 2019–2022. All rights reserved.