> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluggoucash.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Entenda como funcionam os webhooks da Pluggou e como recebê-los com segurança
## Visão geral
Webhooks são notificações HTTP enviadas automaticamente pela Pluggou para o seu servidor sempre que ocorre um evento relevante, como a confirmação de um pagamento, um cancelamento ou um estorno. Isso permite que sua aplicação reaja em tempo real sem precisar consultar a API repetidamente.
A Pluggou envia webhooks para **todos os webhooks ativos** cadastrados na sua conta.
Você pode cadastrar múltiplos webhooks na sua conta para receber notificações em diferentes sistemas simultaneamente.
***
## Headers enviados
Cada webhook enviado pela Pluggou inclui os seguintes headers:
| Header | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | Sempre `application/json`. |
| `X-Webhook-Event-ID` | UUID único que identifica este envio específico. Use para garantir idempotência (evitar processar o mesmo evento duas vezes). |
| `X-Webhook-Code` | Código de segurança exclusivo da sua conta. Use para validar que o webhook veio da Pluggou e não de terceiros. Pode ser consultado e regenerado no painel. |
| `User-Agent` | Sempre `Pluggou-Webhook/1.0`. Identifica a origem da requisição. |
***
## Tempo limite de resposta
A plataforma aguarda no máximo **1 segundo** para a resposta do seu servidor. Se o servidor não responder dentro desse prazo, o envio é registrado como **falha por timeout**.
Sua API deve responder com um **HTTP 200** o mais rápido possível. Processe a lógica de negócio de forma assíncrona (fila, job, worker, etc.) e retorne o `200` imediatamente. Não execute processamento pesado dentro da rota que recebe o webhook.
### Exemplo recomendado de recebimento
```javascript theme={null}
// Receba o webhook, salve na fila e responda 200 imediatamente
app.post('/webhook', (req, res) => {
const event = req.body;
const webhookCode = req.headers['x-webhook-code'];
// Valide a autenticidade
if (webhookCode !== process.env.PLUGGOU_WEBHOOK_CODE) {
return res.status(401).json({ error: 'Código de webhook inválido' });
}
// Salve na fila para processamento assíncrono
queue.add('process-event', event);
// Responda 200 imediatamente
return res.status(200).json({ received: true });
});
```
***
## Critério de sucesso
O webhook é considerado **entregue com sucesso** quando o seu servidor responde com um HTTP status code entre **200 e 299**. Qualquer outro código (`4xx`, `5xx`) ou ausência de resposta (timeout) é registrado como **falha**.
***
## Retentativas
A plataforma **não realiza retentativas automáticas**. Cada evento é enviado uma única vez. Caso a entrega falhe, o evento fica registrado no histórico com o status de falha.
O usuário pode **reenviar manualmente** qualquer webhook que falhou através do **painel da Pluggou** ([Dashboard](https://pluggoucash.com)), na seção de webhooks.
***
## Segurança — Validando a autenticidade
Para garantir que o webhook recebido é legítimo e não uma tentativa de fraude, valide o header `X-Webhook-Code` em toda notificação recebida.
Acesse o painel da Pluggou para obter o código de segurança da sua conta.
Em cada webhook recebido, compare o valor do header `X-Webhook-Code` com o código armazenado no seu sistema.
Se os valores não coincidirem, rejeite a requisição com um `401 Unauthorized`. Isso impede que terceiros simulem notificações da Pluggou.
Caso suspeite que seu código foi comprometido, regenere-o imediatamente no painel da Pluggou. Após a regeneração, atualize o código no seu sistema.
Nunca confie cegamente em webhooks recebidos sem validar o `X-Webhook-Code`. Qualquer pessoa que conheça sua URL de webhook pode simular uma notificação falsa.
***
## Idempotência
Cada webhook possui dois identificadores únicos:
* **`X-Webhook-Event-ID`** — no header da requisição
* **`id`** — no corpo do payload
Armazene esses identificadores no seu sistema para evitar processar o mesmo evento mais de uma vez, especialmente em caso de reenvio manual.
```javascript theme={null}
// Exemplo de verificação de idempotência
app.post('/webhook', async (req, res) => {
const eventId = req.headers['x-webhook-event-id'];
// Verifique se já processou este evento
const alreadyProcessed = await db.webhookEvents.findOne({ eventId });
if (alreadyProcessed) {
return res.status(200).json({ received: true, duplicate: true });
}
// Registre o evento como processado
await db.webhookEvents.create({ eventId, processedAt: new Date() });
// Processe o evento
queue.add('process-event', req.body);
return res.status(200).json({ received: true });
});
```
Mesmo que você retorne `200` para um evento duplicado, a boa prática é registrar que o evento já foi processado e não executar a lógica de negócio novamente.
***
## Resumo do fluxo
```
Evento ocorre → Pluggou detecta mudança → Webhook enviado
│
▼
Webhooks ativos
(cadastrados na conta)
│
▼
Seu servidor
(responde 200)
```
Os dados específicos de cada tipo de webhook (campos do payload, status possíveis, exemplos) estão documentados dentro das respectivas categorias (Transações, Saques, etc.).