Webhooks
Webhooks are a method for Basis Theory to send real-time data to your application when a specific event occurs. Unlike traditional APIs that require you to request data from Basis Theory, webhooks automatically push data to a designated URL as soon as the event is triggered.
Each delivery is a POST request carrying one event. Event Types lists the events you can subscribe to and their payloads, and Webhook Delivery describes the request your endpoint receives and how to handle it.
Getting started
Publicly Accessible Endpoint
The webhook receiver must have a publicly accessible URL where Basis Theory can send HTTP requests. This URL will be registered with Basis Theory when you setup the webhook.
The receiver should be capable of handling HTTP POST requests. It's required to use HTTPS to secure the data in transit, protecting it from potential interception.
The endpoint must accept requests without authentication, since Basis Theory does not send credentials with a delivery. Authenticity comes from the signature instead: verify the signature of every delivery before processing it.
Register the Webhook
Using the Basis Theory Portal or Management API, register your webhook URL and the events that should be sent to it. Each tenant may have up to five webhook URLs registered at one time.
Handle Deliveries
Build the receiver against Webhook Delivery. In short:
- Verify the signature on every request.
- Acknowledge with a
2xxstatus within 25 seconds, after storing the delivery. - Expect retries and duplicates, and deduplicate by
event.id. - Reject replayed requests by checking
delivered_at.
A webhook URL that keeps failing is disabled until you re-enable it.