Criar um endpoint para tipos de eventos

Para garantir que as notificações recebidas pelo seu sistema foram enviadas exclusivamente pela nossa plataforma, utilizamos uma assinatura HMAC (Hash-based Message Authentication Code).

Por que o campo "secret" é obrigatório?

O "secret" é uma chave compartilhada que apenas nós e você conhecemos. Ele é utilizado para gerar um hash único do corpo (payload) de cada requisição. Ao receber o webhook, você deve gerar o mesmo hash usando o seu Secret e comparar com o valor enviado no cabeçalho X-Webhook-Signature. Se os valores coincidirem, a integridade e a origem da mensagem estão garantidas.

const crypto = require('crypto');

// Raw body é o corpo de requisição que você vai receber no endpoint cadastrado
function verifyWebhook(secret, signature, rawBody) {
    const hash = crypto
        .createHmac('sha256', secret)
        .update(rawBody)
        .digest('hex');

    return hash === signature;
}

// Uso:
// const isValid = verifyWebhook(process.env.WEBHOOK_SECRET, req.headers['X-Webhook-Signature'], req.rawBody);

import hmac
import hashlib

def verify_signature(secret, signature, payload):
    # O payload deve ser o conteúdo bruto (bytes) da requisição
    expected_signature = hmac.new(
        key=secret.encode('utf-8'),
        msg=payload,
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_signature, signature)

<?php
function verifySignature($secret, $signature, $payload) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    
    // Use hash_equals para comparação segura contra timing attacks
    return hash_equals($expectedSignature, $signature);
}

// Para pegar o payload bruto no PHP:
// $payload = file_get_contents('php://input');
// $signature = $_SERVER['HTTP_X_SIGNATURE'];
?>

Além do mais, é obrigatório que a URL cadastrada possua o protocolo HTTPS para impedir ataques cibernéticos como Man-In-The-Middle.