​
O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente quando eventos acontecem na sua conta. Com webhooks, você não precisa ficar consultando o status das cobranças - a ZucroPay avisa você quando algo acontece.

​
Eventos Disponíveis

EventoDescrição
payment.receivedPagamento confirmado
payment.refundedPagamento estornado
payment.overduePagamento vencido
withdrawal.completedSaque realizado
withdrawal.rejectedSaque rejeitado

​
Configurando Webhooks

​
Pelo Dashboard

  1. Acesse Integrações
  2. Vá na aba Webhooks
  3. Clique em Criar Webhook
  4. Informe a URL e selecione os eventos

​
Pela API

curl -X POST https://api.appzucropay.com/api/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "url": "https://seusite.com/webhook",
    "events": ["payment.received", "payment.refunded"]
  }'

​
Formato do Payload

Quando um evento ocorre, enviamos um POST para sua URL: 
{
  "event": "payment.received",
  "data": {
    "payment_id": "abc123-def456",
    "value": 99.90,
    "net_value": 93.91,
    "status": "RECEIVED",
    "billing_type": "PIX",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    }
  },
  "timestamp": "2026-01-20T13:05:00.000Z"
}

​
Headers Enviados

HeaderDescrição
Content-Typeapplication/json
X-Webhook-EventNome do evento
X-Webhook-SecretSecret configurado (se houver)

​
Implementando seu Webhook

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, data, timestamp } = req.body;
  const secret = req.headers['x-webhook-secret'];
  
  // Valide o secret se configurado
  if (secret && secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Invalid secret');
  }
  
  switch (event) {
    case 'payment.received':
      console.log('Pagamento recebido!', data.payment_id);
      // Liberar produto, enviar email, etc.
      liberarProduto(data);
      break;
      
    case 'payment.refunded':
      console.log('Pagamento estornado!', data.payment_id);
      // Reverter acesso, notificar, etc.
      break;
  }
  
  // IMPORTANTE: Sempre retorne 200
  res.status(200).send('OK');
});

app.listen(3000);

​
Boas Práticas

Seu endpoint deve responder em até 5 segundos com status 200. Se precisar fazer processamento demorado, salve o evento e processe em background.
Podemos reenviar webhooks em caso de falha. Seu código deve ser capaz de processar o mesmo evento múltiplas vezes sem duplicar ações.
Configure um secret e valide em cada webhook recebido para garantir que a requisição veio da ZucroPay.
Salve os webhooks recebidos em um log para debugging e auditoria.

​
Retentativas

Se seu endpoint retornar erro (status != 2xx) ou timeout, tentamos novamente:
TentativaIntervalo
1ªImediata
2ª5 segundos
3ª30 segundos
Após 3 tentativas falhadas, o webhook é marcado como falho no log.

​
Testando Webhooks

Use ferramentas como webhook.site ou ngrok para testar em desenvolvimento: 
# Exponha seu localhost
ngrok http 3000

# Use a URL gerada como endpoint do webhook
# https://abc123.ngrok.io/webhook