Webhooks

Receba notificações em tempo real sobre eventos importantes que acontecem no seu sistema.

O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente para uma URL configurada por você sempre que um evento específico ocorre no sistema. Eles permitem que você receba atualizações em tempo real sem precisar fazer polling (consultas repetidas) à API.

🎯 Casos de Uso:
• Atualizar o status de um pedido quando o pagamento for confirmado
• Enviar e-mails de confirmação automaticamente
• Sincronizar dados entre sistemas
• Acionar automações de marketing

Tipos de Webhooks Disponíveis

Como Configurar Webhooks

1. Configure a URL de Notificação

Você pode configurar a URL de notificação de duas formas:

A) Na Requisição da API

Inclua o parâmetro notification_url ao criar uma cobrança:

{
  "customer": { ... },
  "payment": { ... },
  "products": [ ... ],
  "notification_url": "https://seu-site.com/webhook/aprovei"
}

B) No Painel do Sistema

Configure uma URL padrão em Configurações → Webhooks no painel administrativo.

⚠️ Importante: A URL configurada na requisição tem prioridade sobre a URL padrão configurada no painel.

2. Prepare seu Endpoint

Seu endpoint deve:

• Aceitar requisições POST com Content-Type: application/json
• Responder com status HTTP 200 OK em caso de sucesso
• Processar a requisição em menos de 10 segundos
• Ser acessível via HTTPS (recomendado)

3. Implemente o Processamento

<?php

// Recebe o payload do webhook
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Valida se os dados foram recebidos
if (!$data) {
    http_response_code(400);
    exit('Invalid payload');
}

// Processa o webhook
$transactionToken = $data['transaction_token'] ?? null;
$paymentStatus = $data['payment_status'] ?? null;
$externalCode = $data['external_code'] ?? null;

// Registra no log
error_log("Webhook recebido: {$transactionToken} - Status: {$paymentStatus}");

// Atualiza o pedido no seu sistema
if ($paymentStatus === 'approved') {
    // Marca o pedido como pago
    updateOrder($externalCode, 'paid');
    
    // Envia e-mail de confirmação
    sendConfirmationEmail($externalCode);
    
} elseif ($paymentStatus === 'refunded' || $paymentStatus === 'chargeback') {
    // Marca o pedido como estornado
    updateOrder($externalCode, 'refunded');
    
    // Notifica o cliente
    sendRefundNotification($externalCode);
}

// Retorna sucesso
http_response_code(200);
echo json_encode(['status' => 'success']);

Segurança e Boas Práticas

1. Validação de IP (Opcional)

Para maior segurança, você pode validar que as requisições estão vindo dos nossos servidores:

<?php

$allowedIPs = [
    '123.456.789.0', // IP do servidor (exemplo)
    // Adicione outros IPs autorizados
];

$clientIP = $_SERVER['REMOTE_ADDR'] ?? '';

if (!in_array($clientIP, $allowedIPs)) {
    http_response_code(403);
    exit('Forbidden');
}

2. Processamento Assíncrono

Para evitar timeouts, processe os webhooks de forma assíncrona usando filas:

<?php

// Recebe o payload
$payload = file_get_contents('php://input');

// Adiciona na fila para processamento
Queue::push('ProcessWebhook', $payload);

// Retorna sucesso imediatamente
http_response_code(200);
echo json_encode(['status' => 'queued']);

3. Idempotência

O mesmo webhook pode ser enviado mais de uma vez. Use o transaction_token para garantir que cada evento seja processado apenas uma vez:

<?php

$transactionToken = $data['transaction_token'];

// Verifica se já processou este webhook
if (webhookWasProcessed($transactionToken)) {
    http_response_code(200);
    exit('Already processed');
}

// Processa o webhook
processWebhook($data);

// Marca como processado
markWebhookAsProcessed($transactionToken);

Retry Logic (Tentativas)

🔄 Sistema de Retentativas: Se seu endpoint não responder com sucesso (HTTP 200-299), faremos até 5 tentativas de envio com intervalos crescentes:

• 1ª tentativa: Imediato
• 2ª tentativa: 1 minuto
• 3ª tentativa: 5 minutos
• 4ª tentativa: 30 minutos
• 5ª tentativa: 2 horas

Testando Webhooks

Durante o desenvolvimento, você pode usar ferramentas como:

• webhook.site - Cria URLs temporárias para testar
• ngrok - Expõe seu localhost para a internet
• RequestBin - Inspeciona requisições HTTP

# Instale o ngrok
# https://ngrok.com/download

# Exponha sua aplicação local
ngrok http 8000

# Use a URL gerada como notification_url
# Exemplo: https://abc123.ngrok.io/webhook

Logs e Monitoramento

Você pode visualizar o histórico de webhooks enviados em Integrações → Logs no painel administrativo. Lá você encontrará:

• Data e hora do envio
• Payload completo enviado
• Resposta do seu servidor
• Status HTTP retornado
• Número de tentativas