Webhooks assinados: como validar as chamadas do Krivo Forms

Um webhook é a forma mais simples de levar cada resposta para fora do WordPress: n8n, Make, Zapier, RD Station ou um endpoint seu. O problema é que qualquer pessoa que descubra a URL poderia enviar dados falsos para ela. A assinatura HMAC resolve isso.

O que o Krivo Forms envia

Cada chamada leva o corpo em JSON e três cabeçalhos relevantes:

• X-Krivo-Timestamp: o instante do envio.
• X-Krivo-Signature: o HMAC-SHA256, em hexadecimal, de {timestamp}.{corpo}.
• X-Krivo-Source: de qual integração veio a chamada.

O segredo nunca viaja na requisição. Quem recebe recalcula a assinatura com o segredo que também conhece e compara.

Verificando em PHP

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_KRIVO_TIMESTAMP'];
$sig  = $_SERVER['HTTP_X_KRIVO_SIGNATURE'];

$esperada = hash_hmac('sha256', $ts . '.' . $body, $segredo);

if (!hash_equals($esperada, $sig)) {
    http_response_code(401);
    exit;
}

Use sempre hash_equals (ou o equivalente da sua linguagem) para comparar em tempo constante, e rejeite chamadas com timestamp muito antigo para evitar reenvios maliciosos.

Verificando em Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function valido(body, ts, sig, segredo) {
  const esperada = createHmac("sha256", segredo).update(`${ts}.${body}`).digest("hex");
  const a = Buffer.from(esperada), b = Buffer.from(sig);
  return a.length === b.length && timingSafeEqual(a, b);
}

Tentativas e registro

Se o destino não responder com sucesso, o plugin tenta de novo automaticamente, com intervalos de 1 segundo, 60 segundos e 300 segundos. Cada tentativa fica registrada, e você pode reenviar manualmente uma entrega pela caixa de respostas.

Outras proteções

• Só são aceitas URLs HTTPS.
• O plugin bloqueia destinos internos (proteção contra SSRF).
• Nada é enviado até você ativar a integração.

No painel de integrações há um botão de teste: ele envia uma resposta de exemplo para o seu endpoint, para você validar a assinatura antes de publicar o formulário.