Verificação de webhooks

Headers Enviados nos Webhooks

Todos os webhooks são enviados com headers especiais para validação e identificação:

POST /your-webhook-url HTTP/1.1
Host: your-api.example.com
Content-Type: application/json
User-Agent: Bifrost/1.0
X-Bifrost-Webhook-Type: payment_processed
X-Bifrost-Timestamp: 1728138000
X-Bifrost-Delivery: 9f2b1c745ae34d1890c61e7d34b0af52
X-Bifrost-Signature: v1=6f3a...c81d
X-Bifrost-Version: 1.0

X-Bifrost-Signature, X-Bifrost-Timestamp e X-Bifrost-Delivery acompanham toda entrega. São eles que provam a origem da mensagem.

Tipos de webhook

O campo event do corpo diz o que aconteceu. Estes são todos os valores que ele pode ter:

X-Bifrost-Webhook-Type só nomeia a família do aviso: todo evento de depósito, inclusive payment_detected e payment_reversed, chega com payment_confirmed nesse cabeçalho, e um payout que falhou chega com payment_processed. Decida sempre pelo campo event do corpo.

Entrega e retentativas

Cada aviso é um POST com corpo JSON para a webhook_url que você cadastrou. O que conta como entregue, e o que acontece quando não é:

• Responda com qualquer status 2xx em até 30 segundos (a conexão em si precisa abrir em até 10 segundos). Qualquer outro status, inclusive 3xx, timeout ou erro de conexão, conta como falha.
• Redirecionamentos não são seguidos. O certificado TLS é verificado, HTTPS é obrigatório em produção, e a conexão é feita por IPv4 ao endereço validado para o seu host.
• Uma entrega que falhou é tentada de novo cerca de 5 minutos depois, até 10 tentativas no total. Depois da décima falha o aviso fica marcado como failed e pode ser reenviado pelo painel.
• Toda tentativa leva o mesmo corpo, um X-Bifrost-Delivery e um X-Bifrost-Timestamp novos, e uma assinatura calculada para eles.
• O mesmo aviso pode, portanto, chegar mais de uma vez. Deduplique por data.internal_reference junto com event (nos avisos de endereço fixo, wallet junto com event).
• Responda primeiro e processe depois: fazer trabalho lento antes de responder é o caminho mais comum para estourar o limite de 30 segundos.

O Selo de Heimdall

Como confirmar que a mensagem veio mesmo da ponte

O endereço que recebe seus webhooks é público: qualquer um que descubra a URL pode enviar uma requisição para ela. Sem verificação, um POST forjado anunciando pagamento aprovado é indistinguível de um pagamento real, e costuma virar mercadoria liberada sem que o dinheiro tenha entrado.

v1
{X-Bifrost-Timestamp}
{X-Bifrost-Delivery}
SHA256_HEX(RAW_BODY)

function verifyBifrostWebhook(string $rawBody, array $headers, string $key): bool
{
    $signature = $headers['X-Bifrost-Signature'] ?? '';
    $timestamp = $headers['X-Bifrost-Timestamp'] ?? '';
    $delivery  = $headers['X-Bifrost-Delivery'] ?? '';

    if ($signature === '' || $timestamp === '' || $delivery === '') {
        return false;
    }

    // Reject stale messages. Five minutes is a comfortable margin
    // for clock drift between servers.
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $canonical = implode("\n", [
        'v1',
        $timestamp,
        $delivery,
        hash('sha256', $rawBody),
    ]);

    $expected = 'v1=' . hash_hmac('sha256', $canonical, $key);

    // hash_equals, not ==: the comparison must take the same time
    // regardless of where the strings diverge.
    return hash_equals($expected, $signature);
}