Skip to content

Webhooks

Preflow notifies your system when something happens: a WhatsApp message is received, sent, delivered, read or fails; a template is approved or rejected. You register an https:// URL (the endpoint), choose the events, and Preflow sends a signed POST to it for each event.

  • Set it up on the screen (Settings → Integrations → API & webhooks) or through the API (scope webhooks:manage). Up to 10 endpoints per workspace.
  • Each notification carries the resource (message text, phone number, lead). Through the API, a key can only subscribe to or read (GET /v1/events/{id}) an event type if it has the read scope of that type’s module: whatsapp.* → whatsapp:read, lead.* → leads:read, account.* → accounts:read, meeting.* → meetings:read. Changing the URL or the events, or re-enabling, also requires those scopes. If the key that created the endpoint loses one of them, deliveries of that type are cancelled (last_error: event_scope_missing).
  • Each notification carries the ids to fetch the full resource from the API.
  • Format of each event: Events. Routes: API reference.
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"]
}

201 response:

{
"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="
}

The secret is shown only once in the API. Store it in the secret vault of the server that receives the webhooks. Repeating the request with the same Idempotency-Key returns the endpoint with secret: null and secret_redacted: true; if you lose the secret, rotate it. On the screen, an admin can view the secret again (“Show secret”); every view is logged.

The URL must be https://, with no username or password. Internal, private, loopback, link-local, cloud-metadata or Preflow’s own addresses are refused (webhook_url_not_allowed), at setup and again on every delivery (DNS is resolved every time and every address must be public).

Route What it does
GET /v1/event-types Events an endpoint can subscribe to
GET /v1/webhook-endpoints The workspace’s endpoints (without the secret)
POST /v1/webhook-endpoints Creates one (returns the secret)
GET /v1/webhook-endpoints/{id} One endpoint
PATCH /v1/webhook-endpoints/{id} Changes url, events, description or status (active/disabled)
DELETE /v1/webhook-endpoints/{id} Deletes it (along with its secret and delivery log)
POST /v1/webhook-endpoints/{id}/rotate-secret New secret; the previous one stays valid for 24 more hours
POST /v1/webhook-endpoints/{id}/test Sends a webhook.test event
GET /v1/webhook-endpoints/{id}/deliveries Delivery log (30 days): status, HTTP code and duration
POST /v1/webhook-deliveries/{id}/retry Redelivers now (not one that already succeeded; up to 10 per minute per endpoint)
GET /v1/events/{id} An event from the last 30 days, with its deliveries

Every webhook is a POST with Content-Type: application/json and this envelope:

{
"id": "evt_9b2f0c1d4e5a46b7a8c9d0e1f2a3b4c5",
"type": "whatsapp.message.received",
"created_at": "2026-11-16T15:04:05.123Z",
"workspace_id": "6e0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
"data": { }
}

Headers (Standard Webhooks spec):

Header Value
webhook-id The event id. It is the same on every attempt: use it to deduplicate.
webhook-timestamp Unix seconds of this attempt.
webhook-signature v1,<signature>; for 24 h after a secret rotation, two of them, separated by a space.

The events and the data of each one are in Events.

  1. Read the raw body (the bytes as they arrived; don’t reformat the JSON).
  2. Build "{webhook-id}.{webhook-timestamp}.{body}".
  3. The key is the secret without the whsec_ prefix, base64-decoded.
  4. Compute HMAC-SHA256, base64-encode it and compare it (in constant time) with each v1,… value in the webhook-signature header. One match is enough.
  5. Reject a webhook-timestamp more than 5 minutes off from your clock.
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);
// Deduplicate by event.id and respond quickly; process in the background.
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, not reformatted
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)
# Deduplicate by event["id"] and respond quickly.
return "", 204
<?php
$secret = getenv('PREFLOW_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input'); // raw body
$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);
// Deduplicate by $event['id'] and respond quickly.
http_response_code(204);

The official Standard Webhooks libraries (Node, Python, PHP, Go, Java, Ruby, C#, Rust) also verify Preflow’s signature.

  • At least once, no guaranteed order. The same event may arrive more than once (e.g. your response got lost): deduplicate by id. To order a message’s statuses, use status_at.
  • Success is any 2xx within 10 s. A 3xx (Preflow doesn’t follow redirects), 4xx, 5xx, network error or timeout is a failure. Your response body is neither read nor stored.
  • Retries after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h, 12 h and 24 h (10 attempts over about 2 days). After that the delivery is marked failed; redeliver it from the screen or with POST /v1/webhook-deliveries/{id}/retry.
  • At most 5 concurrent deliveries per endpoint; while it is failing, one at a time. Preflow’s delivery capacity is shared across endpoints: one server being down doesn’t delay the others.
  • An endpoint failing for 3 days in a row (with no success in between and no gap of more than 25 h between failures) is disabled (status: "disabled", disabled_reason: "failing") and the workspace admins are notified. Fix it and re-enable it with PATCH … { "status": "active" }.
  • A disabled endpoint receives nothing: pending deliveries are cancelled and new events don’t create deliveries for it.
  • The endpoint belongs to whoever created it. If that person stops being a workspace admin, or the key that created it is revoked, it is disabled (disabled_reason: "creator_lost_access") and the admins are notified. Whoever re-enables it becomes responsible for it.
  • Plan without API access (Free plan): endpoints become paused_plan and nothing is sent. Deliveries are kept for up to 30 days and go out when the plan comes back; after that they are deleted along with the event and are never sent.
  • 30-day log at GET /v1/webhook-endpoints/{id}/deliveries: status, HTTP code, duration and the latest attempts. Events and deliveries older than 30 days are deleted. last_error: dns_or_address_refused (the connection was never established: the name didn’t resolve, it resolved to an internal, private or Preflow address, the port refused or didn’t respond, or TLS failed; Preflow doesn’t say which, so the log doesn’t reveal network names and ports), timeout or connection_failed (after connecting, the response took more than 10 s or the connection dropped), redirect_not_followed, http_error, invalid_response or event_scope_missing.

POST /v1/webhook-endpoints/{id}/rotate-secret returns the new secret. For 24 h every notification carries both signatures (the new secret’s and the previous one’s): swap the secret on your server within that period and nothing is lost. Another rotation within those 24 h is refused (webhook_rotation_in_progress).

  1. Register the endpoint and store the secret.
  2. Click “Test” on the screen, or call POST /v1/webhook-endpoints/{id}/test (up to 5 per minute per endpoint).
  3. Within ~10 s a signed webhook.test arrives. Check the status and the HTTP code your server returned in GET /v1/webhook-endpoints/{id}/deliveries (or under “Deliveries” on the screen).