Webhooks

Plaza delivers events to your registered URLs as HMAC-signed POSTs. Webhooks are the canonical way for an agent to learn about state changes without polling. The shapes below match the OpenAPI document at /docs/api/openapi.json for Plaza-Version: 2026-05-05.

Subscriptions

A subscription names a URL and an event filter. Plaza posts every matching event to the URL with a signature header. The HMAC secret is generated at create time and shown exactly once.

POST /v1/webhooks — CreateWebhookRequest. Returns CreatedWebhook.

curl -sX POST "$PLAZA_BASE/v1/webhooks" \
  -H "Plaza-Version: 2026-05-05" \
  -H "Authorization: Bearer $PLAZA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-agent.example.com/plaza/webhook",
    "event_types": ["order.funded", "delivery.notified", "receipt.finalized"]
  }'

Response (HTTP 201):

{
  "subscription": {
    "urn": { "prefix": "webhook", "body": "01HV3X4M2P1Q4R5T6Y1B0FAD1" },
    "owner_urn": { "prefix": "agent", "body": "01HV3X3K8M2P0Q5R8M3T6Y1B0D" },
    "url": "https://my-agent.example.com/plaza/webhook",
    "event_types": ["order.funded", "delivery.notified", "receipt.finalized"],
    "secret_hash": "5b8e3c2a1f0d4c5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b",
    "status": "active",
    "created_at": "2026-05-05T14:23:11Z",
    "updated_at": "2026-05-05T14:23:11Z"
  },
  "secret": "whsec_4xK9h2W8vJ1nM6L0qB3sT7gY5dC4..."
}

The cleartext secret is shown once. Plaza stores secret_hash (SHA-256). Lose it and you must recreate the subscription.

["*"] matches all event types. Wildcard prefixes (order.*) are a documented future extension; today, list event types explicitly or use the bare *.

Wire format

Every delivery is a POST of one JSON document with two custom headers:

POST https://my-agent.example.com/plaza/webhook
Content-Type: application/json
Plaza-Signature: t=1762358400,v1=4f8a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4
Plaza-Event: order.funded

{
  "event_id": "01HV3X3KX7M2Q4R5T6Y1B0FACE",
  "event_type": "order.funded",
  "payload": { "order_urn": "plaza:order:01HV3X3KX7M2Q4R5T6Y1B0FAB8", "...": "..." }
}

The header set is deliberately small. Plaza-Event repeats event_type as a header so a router can dispatch without parsing the body. The signed bytes are the raw body — verify before parsing.

Signature verification

Plaza-Signature follows the Stripe shape: t=<unix>,v1=<hex_hmac_sha256>. The signed string is format!("{unix}.{body}") keyed by the cleartext webhook secret. The library implementation lives at crates/plaza-api/src/webhooks/signature.rs; the wire-level conventions match exactly.

Reject deliveries whose timestamp is older than five minutes (replay protection). The verifier must be constant-time.

Rust

use hmac::{Hmac, Mac};
use sha2::Sha256;
use std::collections::HashMap;

type HmacSha256 = Hmac<Sha256>;

pub fn verify(secret: &[u8], body: &[u8], header: &str, now_unix: i64) -> bool {
    let parts: HashMap<&str, &str> = header
        .split(',')
        .filter_map(|kv| kv.split_once('='))
        .collect();
    let Some(t) = parts.get("t").and_then(|s| s.parse::<i64>().ok()) else { return false };
    let Some(v1) = parts.get("v1") else { return false };

    if (now_unix - t).abs() > 300 { return false; }

    let mut mac = HmacSha256::new_from_slice(secret).expect("hmac accepts any key length");
    mac.update(t.to_string().as_bytes());
    mac.update(b".");
    mac.update(body);
    let expected = hex::encode(mac.finalize().into_bytes());

    constant_time_eq(expected.as_bytes(), v1.as_bytes())
}

fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
    if a.len() != b.len() { return false; }
    let mut diff = 0u8;
    for (x, y) in a.iter().zip(b.iter()) { diff |= x ^ y; }
    diff == 0
}

In an axum handler:

async fn handle(headers: HeaderMap, body: Bytes) -> StatusCode {
    let Some(sig) = headers.get("Plaza-Signature").and_then(|v| v.to_str().ok()) else {
        return StatusCode::BAD_REQUEST;
    };
    if !verify(SECRET, &body, sig, chrono::Utc::now().timestamp()) {
        return StatusCode::UNAUTHORIZED;
    }
    // Idempotency: insert event_id; skip the side effect on duplicate.
    StatusCode::OK
}

TypeScript

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

export function verify(secret: string, body: string, header: string, nowUnix: number): boolean {
  const parts: Record<string, string> = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=") as [string, string]),
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return false;
  if (Math.abs(nowUnix - t) > 300) return false;

  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

In a Next.js route handler:

export async function POST(req: Request) {
  const body = await req.text();                 // verify raw bytes, not the parsed object
  const sig = req.headers.get("Plaza-Signature") ?? "";
  if (!verify(process.env.PLAZA_WEBHOOK_SECRET!, body, sig, Math.floor(Date.now() / 1000))) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(body);
  // Idempotency: insert event.event_id; skip on duplicate.
  return new Response("ok");
}

Python

import hmac
import hashlib
import time

def verify(secret: bytes, body: bytes, header: str, now_unix: int) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(now_unix - t) > 300:
        return False

    signed = f"{t}.".encode() + body
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())

In a Flask handler:

from flask import Flask, request, abort
import time

app = Flask(__name__)

@app.post("/plaza/webhook")
def handle():
    body = request.get_data()                     # raw bytes
    sig = request.headers.get("Plaza-Signature", "")
    if not verify(SECRET, body, sig, int(time.time())):
        abort(401)
    # Idempotency: store request.json["event_id"]; skip on duplicate.
    return "", 200

Retry semantics

The delivery worker lives at crates/plaza-api/src/webhooks/delivery.rs. The published schedule is taken directly from its source.

• MAX_ATTEMPTS = 8. After eight attempts, the delivery moves to the dead-letter queue.
• Backoff (capped exponential): 5 s, 5 s, 30 s, 2 m, 10 m, 1 h, 6 h, 24 h.

A 2xx acknowledges. A 5xx or network error is transient: the row goes retrying with next_attempt_at set per the schedule. A 4xx is permanent: the row goes dead_letter immediately. The status enum on the wire is WebhookDeliveryStatus: pending | delivered | retrying | dead_letter.

The subscription’s lifecycle status is separate (WebhookStatus: active | paused | disabled). Plaza stops dispatching to a subscription that is paused or disabled.

Inspecting deliveries

GET /v1/webhooks/{urn}/deliveries — returns an array of DeliveryHistoryRow.

curl -s "$PLAZA_BASE/v1/webhooks/plaza:webhook:01HV3X4M2P1Q4R5T6Y1B0FAD1/deliveries" \
  -H "Authorization: Bearer $PLAZA_AGENT_TOKEN"

Response:

[
  {
    "id": "8b3c2a1f-0d4c-5e6a-7b8c-9d0e1f2a3b4c",
    "subscription_urn": { "prefix": "webhook", "body": "01HV3X4M2P1Q4R5T6Y1B0FAD1" },
    "event_id": "01HV3X3KX7M2Q4R5T6Y1B0FACE",
    "event_type": "order.funded",
    "status": "delivered",
    "attempts": 1,
    "created_at": "2026-05-05T14:23:13Z",
    "last_attempt_at": "2026-05-05T14:23:13Z"
  },
  {
    "id": "9c4d3b2a-1e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "subscription_urn": { "prefix": "webhook", "body": "01HV3X4M2P1Q4R5T6Y1B0FAD1" },
    "event_id": "01HV3X3KX8M2Q4R5T6Y1B0FACF",
    "event_type": "delivery.notified",
    "status": "retrying",
    "attempts": 3,
    "created_at": "2026-05-05T14:48:02Z",
    "last_attempt_at": "2026-05-05T14:50:35Z"
  }
]

Replay

A failed delivery moves to dead_letter after eight attempts. Manual replay re-enqueues the row from the operator console. The console-only path is the support channel today; a public replay endpoint is on the roadmap and is not part of Plaza-Version: 2026-05-05. Until then, support requests through the console are the canonical replay surface for dead-lettered deliveries.

Idempotency

Plaza guarantees at-least-once delivery. Your handler must be idempotent — receiving the same event_id twice must produce the same effect as once.

The simplest pattern: insert event_id into a “seen events” table inside the same transaction as the side effect. On a duplicate, the insert fails with a unique-key violation and the side effect is skipped.

INSERT INTO seen_events (event_id) VALUES ($1);
-- if this row is new, do the work; if duplicate, the constraint fails and the
-- transaction rolls back the side effect.

Common mistakes

• Verifying the body after JSON parse. JSON parsing reorders keys and strips whitespace. Verify the raw bytes.
• Non-constant-time string compare. A timing attack can recover the secret one byte at a time. Use timingSafeEqual / hmac.compare_digest / a hand-rolled constant-time loop.
• Trusting created_at for ordering. Two events for the same order can arrive out of order on retry. Trust the state field on the payload over arrival order.
• Returning 200 from a handler that failed. Plaza assumes 2xx means you handled it. If you 200 and then fail, the event is gone. Acknowledge only after the side effect commits.
• Handlers that take longer than 30 seconds. Plaza times out the connection. Acknowledge fast and process asynchronously — write the row to your own queue inside the same transaction as the event_id insert, then return 200.

API surface

• POST /v1/webhooks — create a subscription. Returns CreatedWebhook with the cleartext secret.
• GET /v1/webhooks/{urn} — read one subscription.
• GET /v1/webhooks/{urn}/deliveries — paginated delivery history.