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.

Authentication

OAuth2

OAuth2 security scheme

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://accounts.brex.com/oauth2/v1/token
Scopes:
  • openid -

    openid

  • offline_access -

    offline access

authorizationCode OAuth Flow
Authorization URL: https://accounts.brex.com/oauth2/v1/auth
Token URL: https://accounts.brex.com/oauth2/v1/token
Scopes:
  • openid -

    openid

  • offline_access -

    offline access

Webhook Subscriptions

Manage webhook subscriptions.

List Webhooks

List the webhooks you have registered

Request
Security:
OAuth2
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
curl -i -X GET \
  https://platform.brexapis.com/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Register Webhook

Register an endpoint to start receiving selected webhook events

Request
Security:
OAuth2
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" "CARD_TRANSACTION_PENDING_STATUS_CHANGED"
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.

Request
Security:
OAuth2
Responses
200

listSecrets 200 response

400

Bad request

401

Unauthorized

403

Forbidden

500

Internal server error

get/v1/webhooks/secrets
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v1/webhooks/secrets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
[
  • {
    }
]

Get Webhook

Get details of a webhook

Request
Security:
OAuth2
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
curl -i -X GET \
  'https://platform.brexapis.com/v1/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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.

Request
Security:
OAuth2
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" "CARD_TRANSACTION_PENDING_STATUS_CHANGED"
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

Request
Security:
OAuth2
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
curl -i -X DELETE \
  'https://platform.brexapis.com/v1/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Webhook Events

Referral EventsWebhook

Referral Events. Reference the Onboarding API for event details.

Request
Security:
OAuth2 (https://onboarding.brexapis.com/referrals)
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.

Request
Security:
OAuth2 (transfers.readonlytransfers)
Request Body schema: application/json
event_type
required
string (WebhookEventType)
transfer_id
required
string
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",
  • "company_id": "string"
}
Copyright © Brex 2019–2022. All rights reserved.