Webhooks
O Preflow avisa o seu sistema quando algo acontece: mensagem de WhatsApp
recebida, enviada, entregue, lida ou com falha; template aprovado ou recusado.
Você cadastra uma URL https:// (o endpoint), escolhe os eventos e o Preflow
faz um POST assinado para ela a cada evento.
- Cadastro pela tela (Configurações → Integrações → API e webhooks) ou pela API
(acesso
webhooks:manage). Até 10 endpoints por workspace. - Cada aviso leva o recurso (texto da mensagem, telefone, lead). Pela API, a chave
só assina ou lê (
GET /v1/events/{id}) um tipo com o acesso de leitura do módulo dele:whatsapp.*→whatsapp:read,lead.*→leads:read,account.*→accounts:read,meeting.*→meetings:read. Mudar a URL ou os eventos, ou religar, também exige esses acessos. Se a chave que criou o endpoint perder um deles, as entregas desse tipo são canceladas (last_error: event_scope_missing). - Cada aviso traz os ids para buscar o recurso completo pela API.
- Formato de cada evento: Eventos. Rotas: Referência da API.
Cadastro
Seção intitulada “Cadastro”POST /v1/webhook-endpointsAuthorization: Bearer pf_live_…Idempotency-Key: 5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2fContent-Type: application/json
{ "url": "https://erp.suaempresa.com.br/webhooks/preflow", "events": ["whatsapp.message.received", "whatsapp.message.status_updated"]}Resposta 201:
{ "id": "3f1d2c4b-5a6e-4f70-8a9b-0c1d2e3f4a5b", "url": "https://erp.suaempresa.com.br/webhooks/preflow", "status": "active", "events": ["whatsapp.message.received", "whatsapp.message.status_updated"], "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwfQmfVNQhnkZ="}O secret aparece uma vez só na API. Guarde no cofre de segredos do servidor
que recebe os webhooks. Repetir o pedido com a mesma Idempotency-Key devolve o
endpoint com secret: null e secret_redacted: true; perdeu o segredo, gire-o. Na tela, um administrador pode ver o segredo de novo
(“Ver segredo”); cada consulta fica registrada.
A URL precisa ser https://, sem usuário e senha. Endereço interno, privado, de
loopback, link-local, de metadados de nuvem ou do próprio Preflow é recusado
(webhook_url_not_allowed), no cadastro e de novo a cada entrega (o DNS é
resolvido toda vez e todos os endereços precisam ser públicos).
| Rota | O que faz |
|---|---|
GET /v1/event-types |
Eventos que um endpoint pode assinar |
GET /v1/webhook-endpoints |
Endpoints do workspace (sem o segredo) |
POST /v1/webhook-endpoints |
Cadastra (devolve o segredo) |
GET /v1/webhook-endpoints/{id} |
Um endpoint |
PATCH /v1/webhook-endpoints/{id} |
Muda url, events, description ou status (active/disabled) |
DELETE /v1/webhook-endpoints/{id} |
Exclui (segredo e log de entregas juntos) |
POST /v1/webhook-endpoints/{id}/rotate-secret |
Segredo novo; o anterior vale mais 24 h |
POST /v1/webhook-endpoints/{id}/test |
Manda um evento webhook.test |
GET /v1/webhook-endpoints/{id}/deliveries |
Log de entregas (30 dias): status, código HTTP e tempo |
POST /v1/webhook-deliveries/{id}/retry |
Reenvia uma entrega agora (não a que já deu certo; até 10 por minuto por endpoint) |
GET /v1/events/{id} |
Um evento dos últimos 30 dias, com as entregas |
O que chega
Seção intitulada “O que chega”Todo webhook é um POST com Content-Type: application/json e este envelope:
{ "id": "evt_9b2f0c1d4e5a46b7a8c9d0e1f2a3b4c5", "type": "whatsapp.message.received", "created_at": "2026-11-16T15:04:05.123Z", "workspace_id": "6e0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "data": { }}Cabeçalhos (padrão Standard Webhooks):
| Cabeçalho | Valor |
|---|---|
webhook-id |
O id do evento. É o mesmo em todas as tentativas: use para deduplicar. |
webhook-timestamp |
Segundos Unix desta tentativa. |
webhook-signature |
v1,<assinatura>; durante 24 h depois de girar o segredo, duas, separadas por espaço. |
Os eventos e o data de cada um estão em Eventos.
Conferir a assinatura
Seção intitulada “Conferir a assinatura”- Leia o corpo cru (os bytes como chegaram; não reformate o JSON).
- Monte
"{webhook-id}.{webhook-timestamp}.{corpo}". - A chave é o segredo sem o prefixo
whsec_, decodificado de base64. - Calcule HMAC-SHA256, codifique em base64 e compare (em tempo constante) com
cada valor
v1,…do cabeçalhowebhook-signature. Basta um bater. - Recuse
webhook-timestampcom mais de 5 minutos de diferença do seu relógio.
Node.js
Seção intitulada “Node.js”import crypto from 'node:crypto';import express from 'express';
const secret = process.env.PREFLOW_WEBHOOK_SECRET; // whsec_…const app = express();
app.post('/webhooks/preflow', express.raw({ type: 'application/json' }), (req, res) => { const id = req.header('webhook-id'); const timestamp = req.header('webhook-timestamp'); const signatures = (req.header('webhook-signature') ?? '').split(' '); if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400);
const key = Buffer.from(secret.slice('whsec_'.length), 'base64'); const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${req.body}`).digest(); const valid = signatures.some((entry) => { const [version, value] = entry.split(','); const given = Buffer.from(value ?? '', 'base64'); return version === 'v1' && given.length === expected.length && crypto.timingSafeEqual(given, expected); }); if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body); // Deduplique por event.id e responda rápido; processe em segundo plano. res.sendStatus(204);});import base64, hashlib, hmac, json, os, timefrom flask import Flask, request, abort
SECRET = os.environ["PREFLOW_WEBHOOK_SECRET"] # whsec_…app = Flask(__name__)
@app.post("/webhooks/preflow")def preflow_webhook(): msg_id = request.headers.get("webhook-id", "") timestamp = request.headers.get("webhook-timestamp", "") signatures = request.headers.get("webhook-signature", "").split(" ") body = request.get_data() # bytes, sem reformatar if not msg_id or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300: abort(400)
key = base64.b64decode(SECRET.removeprefix("whsec_")) digest = hmac.new(key, f"{msg_id}.{timestamp}.".encode() + body, hashlib.sha256).digest() expected = base64.b64encode(digest).decode() if not any( part.startswith("v1,") and hmac.compare_digest(part[3:], expected) for part in signatures ): abort(401)
event = json.loads(body) # Deduplique por event["id"] e responda rápido. return "", 204<?php$secret = getenv('PREFLOW_WEBHOOK_SECRET'); // whsec_…$body = file_get_contents('php://input'); // corpo cru$id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';$timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';$signatures = explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '');
if ($id === '' || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) { http_response_code(400); exit;}
$key = base64_decode(substr($secret, strlen('whsec_')));$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));
$valid = false;foreach ($signatures as $part) { [$version, $value] = array_pad(explode(',', $part, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $value)) { $valid = true; }}if (!$valid) { http_response_code(401); exit;}
$event = json_decode($body, true);// Deduplique por $event['id'] e responda rápido.http_response_code(204);As bibliotecas oficiais do Standard Webhooks (Node, Python, PHP, Go, Java, Ruby, C#, Rust) também conferem a assinatura do Preflow.
Entrega
Seção intitulada “Entrega”- Pelo menos uma vez, sem ordem garantida. O mesmo evento pode chegar mais de
uma vez (ex.: a sua resposta se perdeu): deduplique pelo
id. Para ordenar status de uma mensagem, usestatus_at. - Sucesso é qualquer 2xx em até 10 s. 3xx (o Preflow não segue redirecionamento), 4xx, 5xx, erro de rede ou demora é falha. O corpo da sua resposta não é lido nem guardado.
- Novas tentativas depois de 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h, 12 h e
24 h (10 tentativas em cerca de 2 dias). Depois disso a entrega fica como
failed; reenvie pela tela ou porPOST /v1/webhook-deliveries/{id}/retry. - No máximo 5 entregas ao mesmo tempo para cada endpoint; enquanto ele está falhando, uma por vez. As vagas do Preflow são repartidas entre os endpoints: um servidor fora do ar não atrasa os outros.
- Endpoint falhando há 3 dias seguidos (sem nenhum sucesso no meio e sem
intervalo de mais de 25 h entre as falhas) é desligado
(
status: "disabled",disabled_reason: "failing") e os administradores do workspace recebem um aviso. Corrija e religue comPATCH … { "status": "active" }. - Endpoint desligado não recebe nada: as entregas pendentes são canceladas e os eventos novos não geram entrega para ele.
- O endpoint é de quem o criou. Se essa pessoa deixa de administrar o
workspace, ou a chave que o criou é revogada, ele é desligado
(
disabled_reason: "creator_lost_access") e os administradores são avisados. Quem religa passa a responder por ele. - Plano sem API (Gratuito): os endpoints ficam
paused_plane nada sai. As entregas ficam guardadas por até 30 dias e saem quando o plano volta; depois disso são apagadas junto com o evento e não saem mais. - Log de 30 dias em
GET /v1/webhook-endpoints/{id}/deliveries: status, código HTTP, tempo e as últimas tentativas. Eventos e entregas com mais de 30 dias são apagados.last_error:dns_or_address_refused(a conexão não chegou a ser estabelecida: o nome não resolveu, resolveu para um endereço interno, privado ou do Preflow, a porta recusou ou não respondeu, ou o TLS falhou; o Preflow não diz qual, para o log não revelar nomes e portas da rede),timeoutouconnection_failed(depois de conectar, a resposta demorou mais de 10 s ou a conexão caiu),redirect_not_followed,http_error,invalid_responseouevent_scope_missing.
Girar o segredo
Seção intitulada “Girar o segredo”POST /v1/webhook-endpoints/{id}/rotate-secret devolve o segredo novo. Durante
24 h cada aviso leva as duas assinaturas (a do segredo novo e a do anterior):
troque o segredo no seu servidor nesse período e nada se perde. Uma nova rotação
nessas 24 h é recusada (webhook_rotation_in_progress).
- Cadastre o endpoint e guarde o segredo.
- “Testar” na tela, ou
POST /v1/webhook-endpoints/{id}/test(até 5 por minuto por endpoint). - Em até ~10 s chega um
webhook.testassinado. Confira emGET /v1/webhook-endpoints/{id}/deliveries(ou em “Entregas” na tela) o status e o código HTTP que o seu servidor respondeu.