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 Unixwebhook-signature: a assinatura no formatov1,<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
- Montamos o texto
{webhook-id}.{webhook-timestamp}.{corpo}, com pontos entre as partes e o corpo da requisição sem alterações. - A partir dele, calculamos um HMAC com SHA-256. A chave é o seu segredo de assinatura, exatamente o texto que mostramos a você.
- O resultado é codificado em Base64 e escrito em
webhook-signature, comv1,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-signaturefoi 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.


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