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:

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


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

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