Authentication & security

Webhooks let Pocketsflow talk directly to your systems, so every request must be authenticated before you act on it. Pocketsflow signs each delivery with an HMAC-SHA256 signature you can verify with a shared secret, and stamps it with a unique event id you can use to drop duplicates and replays.

Signing secret

Each webhook endpoint has its own signing secret (a 48-character hex string). You receive it once, in the response to POST /webhooks:

{
  "id": "6a43ca9f7e229e3568f9c9bb",
  "url": "https://acme.com/webhooks/pocketsflow",
  "events": ["order.completed", "invoice.payment_succeeded"],
  "description": "Production endpoint",
  "secret": "431b749a23715a17f15a0ecd60c0978403f7b3c7c85a8b94"
}

The secret is returned when the endpoint is created, by GET /webhooks/{id}, and by POST /webhooks/{id}/rotate-secret. GET /webhooks (the list) never returns secrets. Store it immediately in a secret manager or environment variable.

Rotating the secret

POST /webhooks/{id}/rotate-secret replaces the endpoint’s signing secret and returns the new one once:

{
  "id": "6a43ca9f7e229e3568f9c9bb",
  "secret": "9f2c4e1ab07d5c3e8f6a1b2d4c6e8f0a1b3c5d7e9f1a2b3c"
}

The old secret stops working immediately — deliveries from that moment on are signed with the new one. Deploy the new secret to your endpoint right after rotating (or briefly accept both while you roll it out).

How Pocketsflow signs a request

For each delivery, Pocketsflow:

Builds the JSON body once: the envelope fields id, type and created, then your event data, then webhookId.
Signs the exact bytes of that body — two ways, described below.
Sends those same bytes as the request body.

Header	Value
`X-Pocketsflow-Signature-V2`	`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<rawBody>")>` — recommended.
`X-Pocketsflow-Signature`	Hex HMAC-SHA256 of the raw request body (legacy, still sent on every delivery).
`X-Pocketsflow-Event`	The event type (for example `order.completed`). Same as the body’s `type`.
`X-Pocketsflow-Event-Id`	Unique event id (`evt_…`). Same as the body’s `id`.
`X-Pocketsflow-Timestamp`	Unix epoch milliseconds the attempt was sent (informational, not signed).

The envelope fields in the body:

Field	Description
`id`	Unique event id (`evt_` + 24 hex characters). Identical on every retry and redelivery of the same event — use it to deduplicate.
`type`	The event type, for example `order.completed`.
`created`	Unix timestamp (seconds) when the event was created.
`test`	`true` on deliveries sent by `POST /webhooks/{id}/test`. Absent otherwise.
`webhookId`	The endpoint the event was delivered to.

Verifying the signature (V2, recommended)

X-Pocketsflow-Signature-V2 binds a timestamp to the body, so a captured request can’t be replayed later with a fresh timestamp.

Read the raw body

Capture the request body as raw bytes before any JSON parsing or middleware re-serializes it. In Express, use express.raw({ type: "application/json" }) for the webhook route.

Parse the header

Split X-Pocketsflow-Signature-V2 on , into t=<seconds> and v1=<hex>.

Check the timestamp

Reject the request if t is more than 5 minutes away from your current time.

Recompute the HMAC

Compute HMAC-SHA256(secret, t + "." + rawBody) and hex-encode it.

Compare in constant time

Compare your digest to v1 with a timing-safe comparison (crypto.timingSafeEqual, hmac.compare_digest, hash_equals). Reject with 400 if they differ.

Deduplicate, then process

Skip the event if you’ve already handled its X-Pocketsflow-Event-Id (also in the body as id). Otherwise record the id, parse the JSON, route on type, and process.

Node.js

import crypto from "crypto";

const TOLERANCE_SECONDS = 5 * 60;

function verifyWebhookV2(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    (signatureHeader || "").split(",").map((part) => part.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !parts.v1) return false;

  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) return false; // too old (or clock skew) — reject

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody) // exact bytes, not the re-serialized object
    .digest("hex");

  const a = Buffer.from(parts.v1, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

TOLERANCE_SECONDS = 5 * 60

def verify_webhook_v2(raw_body: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(int(time.time()) - timestamp) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(parts.get("v1", ""), expected)

The signed body includes webhookId and the envelope fields, so verifying against a re-serialized copy of the parsed JSON can change key order or whitespace and break the signature. Always hash the raw request bytes exactly as received.

Deduplicating events

Pocketsflow retries failed deliveries (see Consuming webhooks) and you can redeliver an event from the delivery log, so the same event can reach you more than once. Every copy carries the same event id in X-Pocketsflow-Event-Id and the body’s id. Store the ids you’ve processed (keeping them for at least a few days is plenty) and skip any id you’ve already seen. Combined with the 5-minute timestamp tolerance, this also blocks replayed requests.

Legacy signature (V1)

X-Pocketsflow-Signature is still sent on every delivery so existing integrations keep working. It is the hex HMAC-SHA256(secret, rawBody) of the raw body only:

Node.js

import crypto from "crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody) // exact bytes, not the re-serialized object
    .digest("hex");

  const a = Buffer.from(signatureHeader || "", "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

V1 does not cover the timestamp, so on its own it can’t stop a captured request from being replayed. If you stay on V1, deduplicate on the event id and treat X-Pocketsflow-Timestamp as a secondary freshness check only. New integrations should verify V2.

Additional defenses

Serve your endpoint over HTTPS with a valid certificate (Pocketsflow only delivers to https:// URLs on public addresses; it follows up to 3 307/308 redirects, re-checking each hop the same way, and any other 3xx counts as a failed delivery).
Validate Content-Type: application/json and the payload shape before acting.
Respond fast — deliveries time out after 5 seconds. Acknowledge with a 2xx and offload work to a queue.
Restrict inbound access with a firewall/WAF if feasible, and never expose sensitive internal services directly.

Handling secrets safely

Store secrets in environment variables or a secret manager — never in source control or client-side code.
Use a distinct endpoint (and therefore secret) per environment; keep test-mode and live-mode endpoints separate.
Rotate a secret with POST /webhooks/{id}/rotate-secret if you suspect exposure or change infrastructure ownership.

Overview

API reference

Node.js SDK

Webhooks

Signing secret

Rotating the secret

How Pocketsflow signs a request

Verifying the signature (V2, recommended)

Deduplicating events

Legacy signature (V1)

Additional defenses

Handling secrets safely

​Signing secret

​Rotating the secret

​How Pocketsflow signs a request

​Verifying the signature (V2, recommended)

​Deduplicating events

​Legacy signature (V1)

​Additional defenses

​Handling secrets safely

​Related topics

Signing secret

Rotating the secret

How Pocketsflow signs a request

Verifying the signature (V2, recommended)

Deduplicating events

Legacy signature (V1)

Additional defenses

Handling secrets safely

Related topics