FlowModels

Verificar a assinatura de webhook: código de exemplo para PHP, Node.js e Python

Publicado em 11. novembro 2026

Todo webhook do FlowModels é assinado. Seu servidor deve verificar essa assinatura antes de processar uma entrega. Só assim você sabe que a mensagem veio mesmo de nós e não foi alterada no caminho. Aqui você encontra o procedimento e código de verificação pronto para PHP, Node.js e Python.

O que é enviado

Cada entrega é um POST com JSON e estes três cabeçalhos:

  • webhook-id: o identificador único da entrega. Em repetições, ele continua igual.
  • webhook-timestamp: o momento da assinatura em segundos Unix
  • webhook-signature: a assinatura no formato v1,<Base64>

O corpo sempre tem os campos id, type, created_at e data. Nos eventos response.*, data contém apenas o id e o status da tarefa. O resultado você busca em seguida com GET /v1/responses/{id}.

Como é feita a assinatura

  1. Montamos o texto {webhook-id}.{webhook-timestamp}.{corpo}, com pontos entre as partes e o corpo da requisição sem alterações.
  2. A partir dele, calculamos um HMAC com SHA-256. A chave é o seu segredo de assinatura, exatamente o texto que mostramos a você.
  3. O resultado é codificado em Base64 e escrito em webhook-signature, com v1, na frente.

Importante: use o segredo como texto normal. Ele é uma sequência aleatória de 48 caracteres e não começa com whsec_. Bibliotecas prontas para “Standard Webhooks” removem um prefixo como whsec_, decodificam o restante como Base64 e calculam o HMAC com isso. Com o segredo do FlowModels, isso gera outra assinatura, e a verificação falha. Por isso, use o código curto de verificação abaixo.

Verifique também o timestamp. Recomendamos recusar entregas cujo timestamp difere em mais de cinco minutos do horário do seu servidor. Isso protege contra a reprodução de mensagens interceptadas.

PHP

<?php
$secret    = getenv('FLOWMODELS_WEBHOOK_SECRET');
$body      = file_get_contents('php://input');
$id        = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$header    = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';

if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'v1,' . base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $secret, true));
$valid = false;
foreach (preg_split('/\s+/', trim($header)) as $candidate) {
    if (hash_equals($expected, $candidate)) {
        $valid = true;
        break;
    }
}
if (! $valid) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Processar o evento, por exemplo com base em $event['type']
http_response_code(204);

Node.js com Express

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.FLOWMODELS_WEBHOOK_SECRET;

app.post("/webhooks/flowmodels", express.raw({ type: "application/json" }), (req, res) => {
  const id = req.get("webhook-id") ?? "";
  const timestamp = req.get("webhook-timestamp") ?? "";
  const header = req.get("webhook-signature") ?? "";

  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(400);
  }

  const expected = "v1," + crypto.createHmac("sha256", secret)
    .update(`${id}.${timestamp}.`)
    .update(req.body) // corpo bruto como Buffer
    .digest("base64");

  const valid = header.split(/\s+/).some((candidate) =>
    candidate.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(candidate), Buffer.from(expected)));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // Processar o evento
  res.sendStatus(204);
});

Python com Flask

import base64, hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["FLOWMODELS_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/flowmodels")
def flowmodels_webhook():
    msg_id = request.headers.get("webhook-id", "")
    timestamp = request.headers.get("webhook-timestamp", "")
    header = request.headers.get("webhook-signature", "")
    body = request.get_data()  # bytes brutos

    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        abort(400)

    mac = hmac.new(SECRET, f"{msg_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(mac).decode()
    if not any(hmac.compare_digest(expected, c) for c in header.split()):
        abort(401)

    event = request.get_json()
    # Processar o evento
    return "", 204

Os erros mais comuns

  • O corpo foi alterado antes da verificação. Muitos frameworks leem o JSON automaticamente. Verifique sempre o corpo bruto, exatamente como chegou. Basta um espaço diferente ou acentos recodificados para gerar outra assinatura.
  • O segredo foi decodificado como Base64. Veja acima, use-o como texto.
  • Só um valor de webhook-signature foi verificado. Depois de Rodar segredo, o cabeçalho traz por 24 horas dois valores, separados por um espaço, um para o segredo antigo e outro para o novo. O código acima verifica todos e aceita no primeiro acerto.
  • Horário do servidor errado. Se o relógio do seu servidor estiver bem errado, a verificação de tempo falha. Sincronize por NTP.

O que seu servidor precisa responder

  • Responda com um código de status 2xx, e a entrega é considerada bem-sucedida. Não lemos o conteúdo da sua resposta.
  • Responda em até 10 segundos. Faça o trabalho pesado depois, por exemplo em uma fila.
  • Não seguimos redirecionamentos (3xx), eles são considerados erro.

Se uma entrega não der certo, tentamos de novo depois de cerca de 1, 5, 15 e 60 minutos, até cinco vezes no total. Como uma entrega pode chegar mais de uma vez por causa disso, processe cada webhook-id apenas uma vez. Depois de cinco entregas seguidas com falha definitiva, desativamos o endereço, veja Configurar webhooks do FlowModels.

Testar a verificação

No dashboard, abra o item Webhooks e, no seu endereço, escolha Enviar entrega de teste. Enviamos então um evento webhook.test. No Registo de entregas, você vê com qual código HTTP seu servidor respondeu.

A lista de webhooks com um endereço, seus eventos, o estado e a última entrega

O registro de entregas de um endereço de webhook com evento, estado, tentativas e código HTTP por entrega

Se você perdeu o segredo, gere um novo com Rodar segredo. Mostramos cada segredo apenas uma vez.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP