What is a Webhook?
Webhooks allow your store to receive automatic notifications whenever an important event occurs, such as the approval or expiration of a payment. This way, you can automate processes and easily integrate external systems.How does it work in caBRAPI?
When a payment’s status changes (for example, approved or expired), caBRAPI sends an HTTP POST request to all webhook URLs registered for the store. Each store can register multiple webhooks, respecting the limit of the contracted plan. The maximum limit is shown in the panel and can be queried via API.Supported events
- Payment approved (
APPROVED) - Payment expired (
EXPIRED)
How the encrypted payload works
Thepayload field sent to each webhook is a string encrypted with AES-256-CBC, in the format:
- The IV (initialization vector) and the encrypted content are separated by a colon.
- The cipher key is derived from the store owner’s API Key via SHA-256.
Attention: Your endpoint needs to know the store owner’s API Key in order to decrypt the payload.
Decrypting the payload (Node.js)
Decrypted object structure
Complete receiving example (Node.js)
How to configure your Webhook
- Access your store panel and go to Settings → Webhooks.
- Add one or more URLs — the limit depends on your plan and is shown in the panel.
- When registered, caBRAPI will automatically send a test event (
WEBHOOK_TEST) to validate the endpoint. Your server must respond with status2xx. - From then on, all payment events will be fired automatically to the registered URLs.