Receber com segurança

Receptor completo

Um receptor completo, do pedido chegando até a resposta: confere a assinatura, ignora evento repetido, ignora evento atrasado e responde rápido. Copie e troque só o trecho "libere o acesso".

O que o código faz

  1. Lê o corpo cru do pedido.
  2. Confere a assinatura e a hora (até 5 minutos de diferença). Falhou: 401.
  3. Grava o id do evento. Já existia: responde 200 sem fazer nada (repetição).
  4. Compara a sequencia com a última já processada daquela cobrança. Menor: ignora (evento atrasado).
  5. Trata o evento e responde 200 em até 5 segundos.

Código

<?php
// webhook.php: PHP 8 + MySQL (PDO). Segredo no ambiente, nunca no código.
// Tabela: CREATE TABLE eventos_grinny (id VARCHAR(40) PRIMARY KEY, recurso VARCHAR(64), sequencia BIGINT, criado TIMESTAMP DEFAULT CURRENT_TIMESTAMP);
$pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'), [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);

$corpo = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_GRINNY_SIGNATURE'] ?? ''), $s);
$esperado = hash_hmac('sha256', ($s['t'] ?? '') . '.' . $corpo, getenv('GRINNY_WEBHOOK_SECRET'));
if (!hash_equals($esperado, $s['v1'] ?? '') || abs(time() - (int) ($s['t'] ?? 0)) > 300) {
    http_response_code(401);
    exit;
}

$evento = json_decode($corpo, true);
if (!is_array($evento) || !isset($evento['id'], $evento['tipo'])) {
    http_response_code(400);
    exit;
}
if ($evento['tipo'] === 'teste.ping') {
    http_response_code(200); // botão Testar do painel
    exit;
}

// Qual cobrança, MED ou saque é este evento?
$d = $evento['dados'];
$recurso = $d['cobranca'] ?? $d['id'];
$seq = (int) ($evento['sequencia'] ?? 0);

$pdo->beginTransaction();
// 1) Repetição: o mesmo id nunca é tratado duas vezes.
$novo = $pdo->prepare('INSERT IGNORE INTO eventos_grinny (id, recurso, sequencia) VALUES (?, ?, ?)');
$novo->execute([$evento['id'], $recurso, $seq]);
if ($novo->rowCount() === 0) {
    $pdo->commit();
    http_response_code(200);
    exit;
}
// 2) Atrasado: já tratei um evento mais novo deste mesmo recurso?
$mais = $pdo->prepare('SELECT MAX(sequencia) FROM eventos_grinny WHERE recurso = ? AND id <> ?');
$mais->execute([$recurso, $evento['id']]);
if ((int) $mais->fetchColumn() > $seq) {
    $pdo->commit();
    http_response_code(200);
    exit;
}

switch ($evento['tipo']) {
    case 'venda.aprovada':
        // libere o acesso do pedido $d['referencia'] (valor pago: $d['valor'] centavos)
        break;
    case 'venda.reembolsada':
    case 'venda.contestada':
        // tire o acesso do pedido $d['referencia']
        break;
    case 'venda.expirada':
        // cancele o pedido $d['referencia']
        break;
    case 'med.aberto':
    case 'med.encerrado':
    case 'saque.concluido':
    case 'saque.falhou':
        // registre no seu financeiro
        break;
}
$pdo->commit();
http_response_code(200);

Cuidados

  • Responda primeiro, trabalhe depois. Se o trabalho demora (e-mail, nota fiscal), grave numa fila e responda 200 na hora. Passou de 5 segundos conta como falha e o evento volta.
  • A conferência de repetição precisa ser atômica. No exemplo PHP o INSERT IGNORE com chave primária faz isso: dois avisos iguais ao mesmo tempo não passam os dois.
  • Erro seu = devolva 5xx. Se o banco do seu sistema caiu, responda 500 (e desfaça o registro do evento): assim ele volta mais tarde. Responder 200 sem ter tratado perde a venda.
  • Evento desconhecido: responda 200 e ignore. Novos eventos podem surgir.

No exemplo PHP, o 200 do "já vi este evento" só vale porque o tratamento anterior terminou. Se o seu código gravar o id e depois falhar, desfaça (rollBack) e responda 500, como a transação do exemplo faz quando uma exceção sobe.