> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabrapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Learn how to configure and use webhooks in caBRAPI to automate events in your store.

## 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

The `payload` field sent to each webhook is a string encrypted with **AES-256-CBC**, in the format:

```
<iv_base64>:<encrypted_base64>
```

* 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)

```js theme={null}
import crypto from 'crypto';

function decryptPayload(payload, apiKey) {
  const [ivB64, encryptedB64] = payload.split(":");
  const iv = Buffer.from(ivB64, "base64");
  const encrypted = Buffer.from(encryptedB64, "base64");
  const key = crypto.createHash("sha256").update(apiKey).digest();
  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
  let decrypted = decipher.update(encrypted, undefined, "utf8");
  decrypted += decipher.final("utf8");
  return JSON.parse(decrypted);
}

// Usage:
// const data = decryptPayload(req.body.payload, 'YOUR_API_KEY_HERE');
```

### Decrypted object structure

```json theme={null}
{
  "event": "PAYMENT_STATUS_UPDATE",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "APPROVED",
  "storeId": "b1c1b1c1-b1c1-b1c1-b1c1-b1c1b1c1b1c1",
  "timestamp": 1710000000000
}
```

| Field | Type | Description |
| - | - | - |
| `event` | `string` | Always `PAYMENT_STATUS_UPDATE` |
| `uuid` | `string` | Payment UUID |
| `status` | `string` | `APPROVED`, `EXPIRED`, `REJECTED` or `PENDING` |
| `storeId` | `string` | ID of the store that originated the event |
| `timestamp` | `number` | Timestamp in milliseconds of the send moment |

***

## Complete receiving example (Node.js)

```js theme={null}
import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

function decryptPayload(payload, apiKey) {
  const [ivB64, encryptedB64] = payload.split(":");
  const iv = Buffer.from(ivB64, "base64");
  const encrypted = Buffer.from(encryptedB64, "base64");
  const key = crypto.createHash("sha256").update(apiKey).digest();
  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
  let decrypted = decipher.update(encrypted, undefined, "utf8");
  decrypted += decipher.final("utf8");
  return JSON.parse(decrypted);
}

app.post('/meu-webhook', (req, res) => {
  const { payload } = req.body;
  if (!payload) return res.status(400).send('Payload ausente');

  const data = decryptPayload(payload, process.env.API_KEY);
  console.log('Evento recebido:', data);

  if (data.event === 'PAYMENT_STATUS_UPDATE' && data.status === 'APPROVED') {
    // handle the approved payment here
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook ouvindo na porta 3000'));
```

***

## How to configure your Webhook

1. Access your store panel and go to **Settings → Webhooks**.
2. Add one or more URLs — the limit depends on your plan and is shown in the panel.
3. When registered, caBRAPI will automatically send a test event (`WEBHOOK_TEST`) to validate the endpoint. Your server must respond with status `2xx`.
4. From then on, all payment events will be fired automatically to the registered URLs.

***

## Useful links

* [Introduction to webhooks](https://webhooks.fyi/)
* [Best practices for consuming webhooks](https://hookdeck.com/webhooks/guides)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.