Operator: webhooks

Webhook deliveries carry three headers:

X-Omega-Signature: t=<unix-seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
X-Omega-Event:     operator.task.succeeded.v1
X-Omega-Delivery:  <uuid>

Endpoint secrets are returned once, in the POST /v1/webhook_endpoints response. There is no reveal route; a lost secret is replaced by creating a new endpoint. Subscribe with event_types from the published catalogue; an unknown type is 400 unknown_event_type rather than a subscription that silently receives nothing.

Four verification rules

The TypeScript client’s WebhookVerifier enforces all four. If you verify by hand, so must you.

Verify the raw bytes. The signed string is "<t>.<raw body>". A framework that parsed the JSON and re-serialized it has changed the bytes and the MAC will not match. Use express.raw, fastify with rawBody, await request.text() in Workers, or the request stream in node:http.
Compare in constant time. A === on hex strings leaks the correct MAC one byte at a time.
Bound the timestamp in both directions (default plus or minus 300 seconds). t is inside the MAC so it cannot be re-stamped, but a captured delivery can be re-sent, and a one-sided check would let a single forged far-future stamp replay forever.
Dedupe on the signed envelope’s id, never on a header. The signature covers the body and no header, so X-Omega-Delivery is attacker-controlled on a captured delivery. The verifier returns the signed eventId for exactly this; deliveryId is echoed for logging and is explicitly not authenticated.

import { WebhookVerificationError, WebhookVerifier } from "omegas-operator";

const verifier = new WebhookVerifier({ secret: process.env.OMEGAS_WEBHOOK_SECRET! });

app.post("/hooks", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const { event } = await verifier.verify({ body: req.body, headers: req.headers });
    await handle(event);          // 200 fast; do the slow part out of band
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      res.sendStatus(error.reason === "replayed_delivery" ? 200 : 400);
    } else {
      res.sendStatus(500);        // our bug, not theirs
    }
  }
});

What you answer matters

The sender treats every non-2xx as a delivery failure and disables an endpoint after 20 consecutive failures. Re-enabling is an explicit PATCH /v1/webhook_endpoints/{id} with {"enabled": true}; nothing turns an endpoint back on for you.

Situation	Answer	Why
Verified and handled	`200`
A replayed delivery	`200`	A duplicate is expected traffic under at-least-once delivery, not an error. Answering `400` burns your endpoint’s failure budget on normal traffic.
Any other verification failure	`400`	It will never verify; a retry cannot help.
Your handler threw	`500`	You want the retry.

Receipt is not processing

By default the verifier records an event as seen the moment it verifies. If your handler then throws, the retry is refused as a replay and that event is gone from your system’s point of view. That default makes the common case, an idempotent handler, effectively-once. For the other trade:

const verifier = new WebhookVerifier({ secret, manualCommit: true });

const delivery = await verifier.verify({ body, headers });
await handle(delivery.event);   // throws: nothing recorded, the retry is accepted
await delivery.commit();        // only now is a redelivery treated as a replay

The cost of manualCommit is that two deliveries of the same event arriving concurrently can both be processed. Neither default is universally right; pick the one your handler’s failure mode deserves. The default replay store is in-memory and correct for one process; several instances need a shared store, such as Redis or a unique index on the event id.

Delivery semantics

Delivery is at-least-once and unordered. Order on the envelope’s created_at, never on arrival. operator.webhook.* events are audit-only: they appear in GET /v1/audit and are never delivered, because delivering them would loop a failing endpoint against itself.

Overview

Continuity

Handoff

Operator

Four verification rules

What you answer matters

Receipt is not processing

Delivery semantics

​Four verification rules

​What you answer matters

​Receipt is not processing

​Delivery semantics

Four verification rules

What you answer matters

Receipt is not processing

Delivery semantics