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

> Aprenda como configurar e utilizar webhooks na caBRAPI para automatizar eventos da sua loja.

## O que é um Webhook?

Webhooks permitem que sua loja receba notificações automáticas sempre que um evento importante ocorre, como a aprovação ou expiração de um pagamento. Assim, você pode automatizar processos e integrar sistemas externos facilmente.

## Como funciona na caBRAPI?

Quando o status de um pagamento muda (por exemplo, aprovado ou expirado), a caBRAPI envia uma requisição HTTP POST para **todas as URLs de webhook cadastradas para a loja**.

Cada loja pode cadastrar múltiplos webhooks, respeitando o limite do plano contratado. O limite máximo é exibido no painel e pode ser consultado via API.

### Eventos suportados

* Pagamento aprovado (`APPROVED`)
* Pagamento expirado (`EXPIRED`)

***

## Como funciona o payload criptografado

O campo `payload` enviado para cada webhook é uma string criptografada com **AES-256-CBC**, no formato:

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

* O IV (vetor de inicialização) e o conteúdo criptografado são separados por dois-pontos.
* A chave de cifragem é derivada da **API Key do dono da loja** via SHA-256.

> **Atenção:** Seu endpoint precisa conhecer a API Key do dono da loja para decifrar o payload.

### Decifrando o 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, 'SUA_API_KEY_AQUI');
```

### Estrutura do objeto decifrado

```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 | Descrição |
| - | - | - |
| `event` | `string` | Sempre `PAYMENT_STATUS_UPDATE` |
| `uuid` | `string` | UUID do pagamento |
| `status` | `string` | `APPROVED`, `EXPIRED`, `REJECTED` ou `PENDING` |
| `storeId` | `string` | ID da loja que originou o evento |
| `timestamp` | `number` | Timestamp em milissegundos do momento do envio |

***

## Exemplo completo de recebimento (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'));
```

***

## Como configurar seu Webhook

1. Acesse o painel da sua loja e vá em **Configurações → Webhooks**.
2. Adicione uma ou mais URLs — o limite depende do seu plano e é exibido no painel.
3. Ao cadastrar, a caBRAPI enviará automaticamente um evento de teste (`WEBHOOK_TEST`) para validar o endpoint. Seu servidor deve responder com status `2xx`.
4. A partir daí, todos os eventos de pagamento serão disparados automaticamente para as URLs cadastradas.

***

## Eventos de webhook da loja (API)

A gestão de webhooks (cadastro, listagem e remoção) é feita por loja. Os eventos abaixo são enviados para as URLs cadastradas, com payload criptografado em AES-256-CBC conforme descrito acima.

### Implementados atualmente

A plataforma emite **25 eventos** cobrindo todo o ciclo de vida dos recursos no padrão `recurso.acao`:

* **Lojas (`4`):** `store.created`, `store.updated`, `store.deleted`, `store.reordered`
* **Produtos (`4`):** `product.created`, `product.updated`, `product.deleted`, `product.reordered`
* **Categorias (`4`):** `category.created`, `category.updated`, `category.deleted`, `category.reordered`
* **Cupons (`4`):** `coupon.created`, `coupon.updated`, `coupon.deleted`, `coupon.reordered`
* **Páginas (`2`):** `page.upserted`, `page.deleted`
* **Afiliados (`3`):** `affiliate.created`, `affiliate.updated`, `affiliate.deleted`
* **Pagamentos (`4`):** `payment.created`, `payment.updated`, `payment.deleted`, `payment.status.changed`

**Payload descriptografado (exemplo `store.created`):**

```json theme={null}
{
  "event": "store.created",
  "storeId": "b1c1b1c1-b1c1-b1c1-b1c1-b1c1b1c1b1c1",
  "store": {
    "id": "b1c1b1c1-b1c1-b1c1-b1c1-b1c1b1c1b1c1",
    "name": "Minha Loja",
    "domain": "minhaloja.cabrapi.com.br"
  },
  "timestamp": 1710000000000
}
```

**Payload descriptografado (exemplo `product.created`, `payment.status.changed`, etc.):**

```json theme={null}
{
  "event": "payment.status.changed",
  "storeId": "b1c1b1c1-b1c1-b1c1-b1c1-b1c1b1c1b1c1",
  "data": {
    "id": "a9c8e7d6-...",
    "uuid": "550e8400-...",
    "status": "APPROVED",
    "price": 49.9,
    "gateway": "MERCADO_PAGO"
  },
  "timestamp": 1710000000000
}
```

> Todos os eventos preservam o payload base (`event`, `storeId`, `timestamp`). Os eventos `store.created`, `store.updated` e `store.deleted` mantêm o campo `store` para retrocompatibilidade, enquanto os demais recursos e `store.reordered` utilizam o campo `data`.

### Regras de assinatura

* `events = []` (lista vazia) significa **todos os eventos** (atuais e novos que forem publicados).
* Lista explícita recebe **apenas** os eventos informados; novos eventos não são adicionados automaticamente.
* Ao cadastrar um webhook, a caBRAPI envia `WEBHOOK_TEST`; seu endpoint deve responder com status `2xx`.

## Links úteis

* [Introdução sobre webhooks](https://webhooks.fyi/)
* [Boas práticas para consumir webhooks](https://hookdeck.com/webhooks/guides)


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