Webhooks

Phyzi POSTs a JSON event to your endpoint every time something happens to a release or an order. Register endpoints with POST /v1/webhook-endpoints. Every event is also stored and readable through GET /v1/events, so nothing is lost while your endpoint is down.

The request

POST /webhooks/phyzi HTTP/1.1
Content-Type: application/json
User-Agent: Phyzi-Webhooks/1.0
Phyzi-Signature: t=1793652859,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Phyzi-Event-Id: evt_3k9w2m7q8r1t5v6x0z4a
Phyzi-Event-Type: master_order.shipped

{
  "id": "evt_3k9w2m7q8r1t5v6x0z4a",
  "type": "master_order.shipped",
  "created_at": "2026-11-02T18:04:13.950Z",
  "livemode": false,
  "data": { "master_order": { "id": "mo_…", "status": "shipped", "...": "..." } }
}

• Respond with any 2xx within 10 seconds. Do slow work after responding.
• Anything else (or a timeout) is retried with backoff, starting at 30 seconds, doubling and capped at 1 hour, for about 24 hours. Redirects aren't followed.
• Deduplicate on id. Retries and POST /v1/events/{id}/resend reuse the same event ID.
• Order isn't guaranteed. Use created_at and the resource's status, or re-read it with GET.
• livemode is false in the sandbox.

Verifying signatures

Phyzi-Signature is t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of "<t>.<raw request body>" keyed with your endpoint's secret (whsec_…). While you rotate secrets there can be two v1= values; accept the request if either matches.

Always verify against the raw body bytes. Re-serialised JSON won't match.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPhyzi(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = Number(parts.find(([k]) => k === "t")?.[1]);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return parts.some(([k, v]) => {
    const got = Buffer.from(v ?? "", "hex");
    return k === "v1" && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

// Express: app.post("/webhooks/phyzi", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyPhyzi(req.body.toString("utf8"), req.get("Phyzi-Signature"), process.env.PHYZI_WEBHOOK_SECRET)) return res.sendStatus(400);
//   res.sendStatus(200); handle(JSON.parse(req.body));
// });

Python

import hashlib, hmac, time

def verify_phyzi(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = [p.strip().split("=", 1) for p in header.split(",")]
    try:
        t = int(next(v for k, v in parts if k == "t"))
    except (StopIteration, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)

Reject requests older than 5 minutes (the tolerance above) to block replays.

Rotating the secret

1. POST /v1/webhook-endpoints/{id}/roll-secret returns a new secret. From then on we sign with both the new and the previous secret.
2. Deploy the new secret.
3. POST /v1/webhook-endpoints/{id}/roll-secret with {"expire_previous": true} stops signing with the old one.

Event types

Every data object contains the full current resource, as it would come back from a GET.

A master order's status goes created → proof_ready → (proof_approved | back to created on rejection) → master_built → units_loaded → shipped. Its timeline records when each step happened.