Pular para o conteúdo

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.
POST /v1/webhook-endpoints
Authorization: Bearer pf_live_…
Idempotency-Key: 5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f
Content-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

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.

  1. Leia o corpo cru (os bytes como chegaram; não reformate o JSON).
  2. Monte "{webhook-id}.{webhook-timestamp}.{corpo}".
  3. A chave é o segredo sem o prefixo whsec_, decodificado de base64.
  4. Calcule HMAC-SHA256, codifique em base64 e compare (em tempo constante) com cada valor v1,… do cabeçalho webhook-signature. Basta um bater.
  5. Recuse webhook-timestamp com mais de 5 minutos de diferença do seu relógio.
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, time
from 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.

  • 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, use status_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 por POST /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 com PATCH … { "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_plan e 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), timeout ou connection_failed (depois de conectar, a resposta demorou mais de 10 s ou a conexão caiu), redirect_not_followed, http_error, invalid_response ou event_scope_missing.

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).

  1. Cadastre o endpoint e guarde o segredo.
  2. “Testar” na tela, ou POST /v1/webhook-endpoints/{id}/test (até 5 por minuto por endpoint).
  3. Em até ~10 s chega um webhook.test assinado. Confira em GET /v1/webhook-endpoints/{id}/deliveries (ou em “Entregas” na tela) o status e o código HTTP que o seu servidor respondeu.