Skip to main content

Webhooks Management API

Create Webhook

Create a new Webhook for the Tenant.

POST
https://api.basistheory.com/webhooks
Copy

Permissions

webhooks:create

Request

curl --location 'https://api.basistheory.com/webhooks' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name":"webhook-create",
"url": "https://www.example.com",
"notify_email": "notify@basistheory.com",
"events": [
"token.created"
]
}'

Request Parameters

NameTypeDescription
nameStringThe name of the webhook.
urlStringThe URL to which the webhook sends events.
notify_emailStringAn email address to be notified of event on the webhook. (ie: webhook disabled)
eventsArrayAn array of events that trigger the webhook.

Response

Returns a Webhook if the webhook was created. Returns an error if there were validation errors, or the webhook failed to create.

{
"id": "fa21bc77-8a21-44c5-850e-85443c90791f",
"tenant_id": "064bbc70-204b-4ef1-a757-ec0878be5945",
"status": "enabled",
"name": "webhook-create",
"url": "https://www.example.com",
"notify_email": "notify@basistheory.com",
"events": [
"token.created"
],
"created_by": "dca45353-4f4f-4310-8bcd-eedecac60b46",
"created_at": "2024-08-22T20:09:27.419Z"
}

List Webhooks

GET
https://api.basistheory.com/webhooks
Copy

Permissions

webhooks:read

Request

curl --location 'https://api.basistheory.com/webhooks/' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>'

Returns a paginated object with the data property containing an array of webhooks. Returns an error if applications could not be retrieved.

{
"pagination": {
"page_size": 1
},
"data": [
{
"id": "fa21bc77-8a21-44c5-850e-85443c90791f",
"tenant_id": "064bbc70-204b-4ef1-a757-ec0878be5945",
"status": "enabled",
"name": "webhook-create",
"url": "https://www.example.com",
"notify_email": "notify@basistheory.com",
"events": [
"token.created"
],
"created_by": "dca45353-4f4f-4310-8bcd-eedecac60b46",
"created_at": "2024-08-22T20:09:27.419Z"
}
]
}

Get a Webhook

GET
https://api.basistheory.com/webhook/{id}
Copy

Permissions

webhook:read

Request

curl --location 'https://api.basistheory.com/webhooks/e08b1fa8-172d-4d5c-b4bc-692134162565' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>'

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the application

Response

Returns a webhook with the id provided. Returns an error if the webhook could not be retrieved.

{
"id": "e08b1fa8-172d-4d5c-b4bc-692134162565",
"tenant_id": "9492840c-1308-4f5a-bb03-af66b83a04f9",
"status": "enabled",
"name": "webhook-create",
"url": "https://www.example.com",
"notify_email": "notify@basistheory.com",
"events": [
"token.created"
],
"created_by": "7edfc306-50f6-4df3-b2ac-4f09c49f0392",
"created_at": "2024-08-22T20:16:36.434Z"
}

Update Webhook

Updates a Webhook.

PUT
https://api.basistheory.com/webhooks/{id}
Copy

Permissions

webhooks:update

Request

curl --location --request PUT 'http://api.basistheory.com/webhooks/e08b1fa8-172d-4d5c-b4bc-692134162565' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name":"webhook-create",
"url": "https://www.example1.com",
"notify_email": "notify@basistheory.com",
"status": "enabled",
"events": [
"token.created"
]
}'

Request Parameters

NameTypeDescription
nameStringThe name of the webhook.
urlStringThe URL to which the webhook sends events.
notify_emailStringAn email address to be notified of event on the webhook. (ie: webhook disabled)
statusString (Optional)Enable or disable the webhook. Valid values enabled or disabled
eventsArrayAn array of events that trigger the webhook.

Response

Returns a Webhook if the webhook was created. Returns an error if there were validation errors, or the webhook failed to create.

{
"id": "e08b1fa8-172d-4d5c-b4bc-692134162565",
"tenant_id": "9492840c-1308-4f5a-bb03-af66b83a04f9",
"status": "enabled",
"name": "webhook-create",
"url": "https://www.example.com",
"events": [
"token.created"
],
"created_by": "7edfc306-50f6-4df3-b2ac-4f09c49f0392",
"created_at": "2024-08-22T20:16:36.434Z",
"modified_by": "7edfc306-50f6-4df3-b2ac-4f09c49f0392",
"modified_at": "2024-08-22T20:31:33.663Z"
}

Delete Webhook

Deletes a Webhook.

DELETE
https://api.basistheory.com/webhooks/{id}
Copy

Permissions

webhooks:delete

Request

curl --location --request DELETE 'http://api.basistheory.com/webhooks/7d52263c-2af4-49d7-99ac-1a1c6dc99d66' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>'

Response

Returns a HTTP 204 status if the webhook was deleted.

Get Available Events

Gets a list of valid event types.

GET
https://api.basistheory.com/webhooks/event-types
Copy

Permissions

webhook:read

Request

curl --location 'http://api.basistheory.com/webhooks/event-types' \
--header 'BT-API-KEY: <MANAGEMENT_API_KEY>'

Response

Returns a list of valid event types.

[
"3ds.session.authenticated",
"3ds.session.challenge-result-retrieved",
"3ds.session.created",
...
]