Skip to main content

​
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:
HeaderDescrição
Content-TypeSempre application/json.
X-Webhook-Event-IDUUID único que identifica este envio específico. Use para garantir idempotência (evitar processar o mesmo evento duas vezes).
X-Webhook-CodeCó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-AgentSempre Pluggou-Webhook/1.0. Identifica a origem da requisição.

​
Tempo limite de resposta

A plataforma aguarda no máximo 4 segundos 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

// 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), 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.
1

Consulte seu código de webhook

Acesse o painel da Pluggou para obter o código de segurança da sua conta.
2

Compare o header recebido

Em cada webhook recebido, compare o valor do header X-Webhook-Code com o código armazenado no seu sistema.
3

Rejeite requisições inválidas

Se os valores não coincidirem, rejeite a requisição com um 401 Unauthorized. Isso impede que terceiros simulem notificações da Pluggou.
4

Regenere se necessário

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. 
// 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.).