Webhooks API (0.1)

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.

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
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_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.

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.

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_type": "PURCHASE",
  • "company_id": "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.