FlowModels

Verify the webhook signature: sample code for PHP, Node.js and Python

Published on 11. November 2026

Every FlowModels webhook is signed. Your server should verify this signature before processing a delivery. Only then do you know that the message really comes from us and wasn't altered on the way. Here you'll find the procedure and ready-made verification code for PHP, Node.js and Python.

What is sent along

Each delivery is a POST with JSON and these three headers:

  • webhook-id: the unique identifier of the delivery. It stays the same across retries.
  • webhook-timestamp: the time of the signature in Unix seconds
  • webhook-signature: the signature in the format v1,<Base64>

The body always has the fields id, type, created_at and data. For response.* events, data contains only the job's id and status. You then fetch the result yourself with GET /v1/responses/{id}.

How signing works

  1. We build the text {webhook-id}.{webhook-timestamp}.{body}, with periods in between and the unaltered body of the request.
  2. From that, we calculate an HMAC with SHA-256. The key is your signing secret, exactly the text we showed you.
  3. The result is Base64-encoded and written to webhook-signature with v1, in front.

Important: Use the secret as plain text. It's a random string of 48 characters and doesn't start with whsec_. Off-the-shelf libraries for "Standard Webhooks" remove a prefix like whsec_, decode the rest as Base64 and use that to calculate the HMAC. With the FlowModels secret, that produces a different signature and verification fails. So use the short verification code below.

Also check the timestamp. We recommend rejecting deliveries whose timestamp differs from your server time by more than five minutes. This protects against replays of intercepted messages.

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);
// Process the event, for example based on $event['type']
http_response_code(204);

Node.js with 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) // raw body as a 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"));
  // Process the event
  res.sendStatus(204);
});

Python with 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()  # raw bytes

    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()
    # Process the event
    return "", 204

The most common mistakes

  • The body was changed before verification. Many frameworks parse JSON automatically. Always verify the raw body exactly as it arrived. Even a different space or re-encoded umlauts produce a different signature.
  • The secret was decoded as Base64. See above, use it as text.
  • Only one value in webhook-signature was checked. After Rotate secret, the header contains two values for 24 hours, separated by a space, one each for the old and the new secret. The code above checks all of them and accepts on the first match.
  • Wrong server time. If your server clock is significantly off, the time check fails. Synchronize it with NTP.

What your server must respond

  • Respond with a 2xx status code and the delivery counts as successful. We don't read the content of your response.
  • Respond within 10 seconds. Do any heavy work afterward, for example through a queue.
  • We don't follow redirects (3xx), they count as errors.

If a delivery fails, we try again after about 1, 5, 15 and 60 minutes, up to five times in total. Because a delivery can arrive more than once as a result, process each webhook-id only once. After five permanently failed deliveries in a row, we switch off the address, see Set up FlowModels webhooks.

Test the verification

Open Webhooks in the dashboard and choose Send test delivery for your address. We then send a webhook.test event. In the Delivery log, you can see which HTTP code your server responded with.

The webhook list with an address, its events, the status and the last delivery

The delivery log of a webhook address with event, status, attempts and HTTP code per delivery

If you've lost the secret, generate a new one with Rotate secret. We show each secret only once.

Was this article helpful?

Back to Webhooks, end users & MCP