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-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"]}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 |
What you receive
Section titled “What you receive”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.
Verify the signature
Section titled “Verify the signature”- Read the raw body (the bytes as they arrived; don’t reformat the JSON).
- Build
"{webhook-id}.{webhook-timestamp}.{body}". - The key is the secret without the
whsec_prefix, base64-decoded. - Compute HMAC-SHA256, base64-encode it and compare it (in constant time) with
each
v1,…value in thewebhook-signatureheader. One match is enough. - Reject a
webhook-timestampmore than 5 minutes off from your clock.
Node.js
Section titled “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); // Deduplicate by event.id and respond quickly; process in the background. res.sendStatus(204);});Python
Section titled “Python”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, 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.
Delivery
Section titled “Delivery”- 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, usestatus_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 withPOST /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 withPATCH … { "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_planand 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),timeoutorconnection_failed(after connecting, the response took more than 10 s or the connection dropped),redirect_not_followed,http_error,invalid_responseorevent_scope_missing.
Rotate the secret
Section titled “Rotate the secret”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).
- Register the endpoint and store the secret.
- Click “Test” on the screen, or call
POST /v1/webhook-endpoints/{id}/test(up to 5 per minute per endpoint). - Within ~10 s a signed
webhook.testarrives. Check the status and the HTTP code your server returned inGET /v1/webhook-endpoints/{id}/deliveries(or under “Deliveries” on the screen).