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

Guias de Payload por Evento

Eventos Disponíveis

O campo event do payload identifica o evento. order.created representa o pedido criado após o preenchimento dos dados pessoais; payment.pix.created e payment.boleto.created são emitidos junto com os status pending/processing quando a cobrança correspondente é gerada.

Como Configurar Webhooks

1. Registre seu Endpoint

Você pode registrar webhooks de duas formas:

A) No Painel do Sistema

Cadastre a URL, o token de assinatura e os eventos desejados na área de Webhooks do painel administrativo.

B) Via API Aprovei

Registre programaticamente com POST /webhooks e liste os webhooks da loja com GET /webhooks. Nesse caso, o secret de assinatura é gerado pelo backend e exibido uma única vez na resposta da criação. Cada loja pode ter no máximo 10 webhooks.

2. Prepare seu Endpoint

Seu endpoint deve:

• Aceitar requisições POST com Content-Type: application/json
• Responder com qualquer status HTTP 2xx em caso de sucesso
• Responder em menos de 5 segundos (timeout da entrega)
• Ser acessível via HTTPS (obrigatório para webhooks criados via API v1 em produção)

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
$orderId = $data['orderId'] ?? null;
$status = $data['status'] ?? null;
$event = $data['event'] ?? null;

// Registra no log
error_log("Webhook recebido: {$orderId} - Status: {$status} - Event: {$event}");

// Atualiza o pedido no seu sistema
if ($status === 'paid') {
    // Marca o pedido como pago
    updateOrder($orderId, 'paid');

    // Envia e-mail de confirmação
    sendConfirmationEmail($orderId);

} elseif ($status === 'refunded' || $status === 'chargeback') {
    // Marca o pedido como estornado
    updateOrder($orderId, 'refunded');

    // Notifica o cliente
    sendRefundNotification($orderId);
}

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

Headers da Entrega

Toda entrega é um POST com os headers abaixo:

Segurança e Boas Práticas

1. Valide a Assinatura

Toda entrega é assinada com o secret do webhook (definido por você no painel ou gerado pela API v1). Recalcule o HMAC-SHA256 sobre o body bruto e compare com o header X-Aprovei-Signature:

<?php

$secret = getenv('APROVEI_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_APROVEI_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

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 orderId para garantir que cada evento seja processado apenas uma vez:

<?php

$orderId = $data['orderId'];

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

// Processa o webhook
processWebhook($data);

// Marca como processado
markWebhookAsProcessed($orderId);

Retry Logic (Tentativas)

🔄 Sistema de Retentativas: Se seu endpoint não responder com sucesso (HTTP 2xx), 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

# Cadastre a URL gerada como webhook
# 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