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

> Aprende cómo configurar y utilizar webhooks en caBRAPI para automatizar eventos de tu tienda.

## ¿Qué es un Webhook?

Los webhooks permiten que tu tienda reciba notificaciones automáticas cada vez que ocurre un evento importante, como la aprobación o expiración de un pago. Así, puedes automatizar procesos e integrar sistemas externos fácilmente.

## ¿Cómo funciona en caBRAPI?

Cuando cambia el estado de un pago (por ejemplo, aprobado o expirado), caBRAPI envía una solicitud HTTP POST a **todas las URLs de webhook registradas para la tienda**.

Cada tienda puede registrar múltiples webhooks, respetando el límite del plan contratado. El límite máximo se muestra en el panel y puede consultarse vía API.

### Eventos soportados

* Pago aprobado (`APPROVED`)
* Pago expirado (`EXPIRED`)

***

## ¿Cómo funciona el payload cifrado

El campo `payload` enviado a cada webhook es una cadena cifrada con **AES-256-CBC**, en el formato:

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

* El IV (vector de inicialización) y el contenido cifrado están separados por dos puntos.
* La clave de cifrado se deriva de la **API Key del dueño de la tienda** mediante SHA-256.

> **Atención:** Tu endpoint debe conocer la API Key del dueño de la tienda para descifrar el payload.

### Descifrando el 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);
}

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

### Estructura del objeto descifrado

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

| Campo | Tipo | Descripción |
| - | - | - |
| `event` | `string` | Siempre `PAYMENT_STATUS_UPDATE` |
| `uuid` | `string` | UUID del pago |
| `status` | `string` | `APPROVED`, `EXPIRED`, `REJECTED` o `PENDING` |
| `storeId` | `string` | ID de la tienda que originó el evento |
| `timestamp` | `number` | Timestamp en milisegundos del momento del envío |

***

## Ejemplo completo de recepción (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') {
    // processe o pagamento aprovado aqui
  }

  res.sendStatus(200);
});

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

***

## Cómo configurar tu Webhook

1. Accede al panel de tu tienda y ve a **Configuraciones → Webhooks**.
2. Añade una o más URLs — el límite depende de tu plan y se muestra en el panel.
3. Al registrarlas, caBRAPI enviará automáticamente un evento de prueba (`WEBHOOK_TEST`) para validar el endpoint. Tu servidor debe responder con estado `2xx`.
4. A partir de ahí, todos los eventos de pago se dispararán automáticamente a las URLs registradas.

***

## Enlaces útiles

* [Introducción sobre webhooks](https://webhooks.fyi/)
* [Buenas prácticas para consumir webhooks](https://hookdeck.com/webhooks/guides)
  EOF


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