Skip to main content

O que são Webhooks?

Webhooks são mecanismos que permitem a comunicação automática entre sistemas. Sempre que um evento relevante ocorre na Pronttus (como uma transação, transferência, estorno ou infração), enviamos automaticamente uma requisição HTTP POST para uma URL previamente configurada por você.
Com webhooks, você não precisa fazer polling (consultas repetidas) para verificar o status das transações. Nós notificamos você automaticamente em tempo real.

Benefícios

Tempo Real

Receba notificações instantâneas assim que os eventos ocorrem

Eficiência

Elimine a necessidade de consultas repetidas (polling)

Confiável

Sistema de retry automático com até 3 tentativas

Seguro

Autenticação via secret e headers customizáveis

Como Funciona

1

Configuração

Você registra uma URL de webhook por tipo de operação (ex: Transferência, Recebimento, Estorno, Infrações) no dashboard da Pronttus
2

Assinatura de eventos

Defina quais eventos específicos deseja receber em cada URL configurada
3

Disparo de evento

Quando um evento ocorre, a Pronttus envia automaticamente uma requisição HTTP POST para a URL associada ao tipo
4

Processamento e resposta

Sua aplicação processa o evento e deve retornar um HTTP 2XX (preferencialmente 200) em até 10 segundos para confirmar o recebimento

Configurando Webhooks

1. Acesse o Dashboard

Entre em app.pronttus.com.br e navegue até a seção Webhooks.

2. Configure por Tipo de Operação

A Pronttus permite configurar webhooks específicos para cada categoria de operação:
  • Transferências - Envios PIX e TEDs
  • Recebimentos - Pagamentos e QR Codes PIX
  • Estornos - Devoluções e reembolsos
  • Infrações - Violações de regras PIX
  • Débito/Crédito em conta - Movimentações de saldo
  • Outros eventos - Operações futuras

3. Personalize a Configuração

Para cada webhook, você pode configurar:
Endpoint HTTPS que receberá os eventos. URLs HTTP não são aceitas por questões de segurança.Exemplo: https://api.sua-empresa.com/webhooks/pronttus
Receba alertas automáticos quando houver falhas recorrentes na entrega de webhooks
Adicione headers personalizados para autenticação ou rastreamentoExemplo:
Authorization: Bearer seu_token_secreto
X-Custom-Header: valor_personalizado
Selecione exatamente quais eventos deseja receber para evitar notificações desnecessárias
Pause manualmente o envio de webhooks ou configure pausa automática ao detectar falhas recorrentes
Importante: A URL deve ser HTTPS e retornar resposta em até 10 segundos para evitar timeout e reprocessamento.

Estrutura da Requisição

Cada webhook é enviado via HTTP POST com os seguintes headers e corpo:

Headers Padrão

POST /webhooks HTTP/1.1
Host: sua-url.com
Content-Type: application/json
x-correlation-id: 550e8400-e29b-41d4-a716-446655440000
x-webhook-secret: SEU_WEBHOOK_SECRET
Content-Type
string
Sempre application/json
x-correlation-id
string
UUID único para rastreamento e identificação de reentregas. Use este campo para implementar idempotência
x-webhook-secret
string
Secret configurado no dashboard para validação de autenticidade. Sempre valide este header!

Payload (Corpo da Requisição)

{
  "webhookId": "wh_a1b2c3d4e5f6",
  "type": "transactions.receive",
  "data": {
    // Dados específicos do evento
  }
}

Campos do Payload

webhookId
string
Identificador único do webhook
type
string
Tipo do evento (ex: transactions.receive, transactions.transfer, transactions.chargeback)
data
object
Objeto contendo os dados específicos do evento. A estrutura varia conforme o tipo de evento

Exemplo de Implementação

const express = require('express');
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.PRONTTUS_WEBHOOK_SECRET;

// Armazenar IDs processados para idempotência
const processedWebhooks = new Set();

// Endpoint para receber webhooks
app.post('/webhooks/pronttus', (req, res) => {
  const webhookSecret = req.headers['x-webhook-secret'];
  const correlationId = req.headers['x-correlation-id'];
  const payload = req.body;

  // Valida secret
  if (webhookSecret !== WEBHOOK_SECRET) {
    console.error('Secret inválido');
    return res.status(401).send('Não autorizado');
  }

  // Implementa idempotência usando correlation-id
  if (processedWebhooks.has(correlationId)) {
    console.log('Webhook já processado:', correlationId);
    return res.status(200).send('OK');
  }

  // Processa o evento
  const { webhookId, type, data } = payload;

  try {
    switch (type) {
      case 'transactions.receive':
        console.log('Pagamento recebido:', data.transaction_id);
        // Atualiza banco de dados, envia e-mail, etc.
        break;

      case 'transactions.transfer':
        console.log('Transferência concluída:', data.transfer_id);
        break;

      case 'transactions.chargeback':
        console.log('Estorno recebido:', data.chargeback_id);
        break;

      default:
        console.log('Evento desconhecido:', type);
    }

    // Marca como processado
    processedWebhooks.add(correlationId);

    // IMPORTANTE: Retorna 200 para confirmar recebimento
    res.status(200).json({ status: 'processed' });
  } catch (error) {
    console.error('Erro ao processar webhook:', error);
    // Mesmo com erro, retorna 200 para evitar retry desnecessário
    // se for um erro de lógica de negócio (não de infraestrutura)
    res.status(200).json({ status: 'error', message: error.message });
  }
});

app.listen(3000, () => {
  console.log('Servidor rodando na porta 3000');
});

Segurança e Validação

Validação do Webhook Secret

Sempre valide o header x-webhook-secret antes de processar qualquer webhook:
1

Obtenha o Secret

No dashboard da Pronttus, copie o Webhook Secret fornecido ao configurar cada webhook
2

Compare com o Header

Valide se o valor do header x-webhook-secret corresponde ao secret configurado
3

Rejeite se Inválido

Se o secret não corresponder, retorne HTTP 401 e não processe o evento
const WEBHOOK_SECRET = process.env.PRONTTUS_WEBHOOK_SECRET;

app.post('/webhooks/pronttus', (req, res) => {
  const webhookSecret = req.headers['x-webhook-secret'];
  
  if (webhookSecret !== WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Não autorizado' });
  }
  
  // Processa o webhook...
});
Nunca exponha o webhook secret em código cliente ou repositórios públicos. Use variáveis de ambiente.

Retry e Resiliência

Política de Retry

A Pronttus aplica retentativas automáticas quando a entrega de um webhook falha:
Erros 4XX ou 5XX acionam nova tentativa automaticamente
Serão feitas até 3 novas tentativas em até 10 minutos
Eventos com falha ficam disponíveis para reprocessamento manual no painel da Pronttus
Você receberá notificação por e-mail (se configurado) quando houver falhas recorrentes

Códigos de Resposta Esperados

CódigoDescriçãoAção da Pronttus
2XXEvento recebido com sucessoWebhook marcado como entregue
4XXFalha no envio (problema no seu endpoint)Retry automático
5XXFalha no envio (servidor indisponível)Retry automático
Retorne sempre HTTP 200 (ou qualquer 2XX) para confirmar o recebimento, mesmo que ocorram erros de lógica de negócio no processamento.

Idempotência

Webhooks podem ser entregues mais de uma vez. Implemente idempotência usando o header x-correlation-id:
// Exemplo de verificação de duplicidade usando correlation-id
const processedWebhooks = new Set();

app.post('/webhooks/pronttus', (req, res) => {
  const correlationId = req.headers['x-correlation-id'];

  // Verifica se já processou este webhook
  if (processedWebhooks.has(correlationId)) {
    console.log('Webhook já processado:', correlationId);
    return res.status(200).send('OK');
  }

  // Processa e marca como processado
  processWebhook(req.body);
  processedWebhooks.add(correlationId);

  res.status(200).send('OK');
});
Use o x-correlation-id (não o webhookId) para implementar idempotência, pois o mesmo evento pode ter IDs diferentes em caso de reentrega.

Boas Práticas

Seu endpoint deve retornar status 200 em até 10 segundos. Processe operações demoradas de forma assíncrona.
app.post('/webhooks/pronttus', async (req, res) => {
  // Valida e retorna 200 imediatamente
  if (isValidWebhook(req)) {
    res.status(200).send('OK');
    
    // Processa de forma assíncrona (fila, worker, etc)
    await queueWebhookProcessing(req.body);
  }
});
Rejeite requisições não HTTPS. A Pronttus só envia webhooks para URLs HTTPS.
  • Configure certificado SSL válido
  • Nunca aceite webhooks em URLs HTTP
  • Use TLS 1.2 ou superior
Utilize autenticação via header customizado para segurança adicional:
// Configure no dashboard da Pronttus
Authorization: Bearer seu_token_secreto

// Valide no seu endpoint
const authHeader = req.headers['authorization'];
if (authHeader !== 'Bearer seu_token_secreto') {
  return res.status(401).send('Unauthorized');
}
Use o x-correlation-id para rastrear reentregas e debugar problemas:
const correlationId = req.headers['x-correlation-id'];
console.log(`[${correlationId}] Processando webhook...`);
Salve todos os webhooks recebidos em um banco de dados para auditoria e reprocessamento.
await db.webhooks.create({
  correlation_id: req.headers['x-correlation-id'],
  webhook_id: payload.webhookId,
  type: payload.type,
  payload: payload,
  received_at: new Date()
});
Implemente try-catch robusto. Retorne 200 para erros de lógica de negócio, mas 5XX para erros de infraestrutura.
app.post('/webhooks/pronttus', async (req, res) => {
  try {
    await processWebhook(req.body);
    res.status(200).send('OK');
  } catch (error) {
    if (error.type === 'business_logic') {
      // Erro de lógica - retorna 200 para não retriar
      console.error('Erro de lógica:', error);
      res.status(200).json({ error: error.message });
    } else {
      // Erro de infraestrutura - retorna 500 para retriar
      console.error('Erro de infraestrutura:', error);
      res.status(500).json({ error: 'Server error' });
    }
  }
});
Configure alertas para webhooks que falham repetidamente:
  • Monitore taxa de sucesso/falha
  • Alerte quando houver múltiplas falhas
  • Verifique tempo de resposta
  • Use APM (New Relic, Datadog, etc)
Sempre implemente idempotência usando o x-correlation-id para evitar processar o mesmo evento múltiplas vezes:
  • Use banco de dados ou cache (Redis)
  • Armazene o correlation-id dos eventos processados
  • Verifique antes de processar
  • Retorne 200 para eventos duplicados

Testando Webhooks Localmente

Use ferramentas como ngrok para expor seu localhost durante o desenvolvimento:
# Instale o ngrok
npm install -g ngrok

# Exponha sua porta local
ngrok http 3000

# Use a URL HTTPS fornecida no dashboard da Pronttus
# Exemplo: https://abc123.ngrok-free.app/webhooks/pronttus
O ngrok fornece uma URL HTTPS temporária que você pode usar para testar webhooks localmente sem precisar fazer deploy.

Testando Manualmente

Você pode testar seu endpoint manualmente com cURL:
curl -X POST https://seu-endpoint.com/webhooks/pronttus \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: SEU_SECRET" \
  -H "x-correlation-id: test-123" \
  -d '{
    "webhookId": "test_webhook_123",
    "type": "transactions.receive",
    "data": {
      "transaction_id": "txn_test_456",
      "amount": 10000,
      "status": "paid"
    }
  }'

Ambiente Sandbox

O suporte a Webhooks no ambiente de sandbox está em desenvolvimento. Alguns eventos podem não estar disponíveis para testes ainda.Consulte nossa equipe de suporte para informações atualizadas sobre a disponibilidade de webhooks em sandbox.

Suporte e Ajuda

Precisa de ajuda com webhooks? Nossa equipe está disponível:
CanalInformação
E-mail Técnico[email protected]
WhatsApp+55 (11) 99999-9999
HorárioSegunda a Sexta, 9h às 18h (BRT)
Dashboardapp.pronttus.com.br
Se você está enfrentando falhas recorrentes de entrega de webhooks, verifique:
  • Seu endpoint está respondendo em até 10 segundos?
  • O certificado SSL está válido?
  • O firewall está permitindo requisições da Pronttus?
  • Você está validando corretamente o x-webhook-secret?

Próximos Passos