Receive and test signed webhooks

​

Prerequisites

• A key with both runs:read and runs:write to create or change an endpoint.
• A public HTTPS endpoint on the default port. Localhost, IP literals, private networks, embedded credentials, and unsafe redirect targets are rejected.
• A secret manager for the one-time signing_secret.

​

1. Create an endpoint

curl --fail-with-body https://api.praxa.io/v1/webhooks \
  -H "Authorization: Bearer $PRAXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://events.example.com/webhooks/praxa",
    "event_types": ["run.completed", "run.failed"],
    "description": "Production task outcomes"
  }'

​

2. Verify the raw request

Praxa-Webhook-Id: <event-id>
Praxa-Webhook-Timestamp: <unix-seconds>
Praxa-Webhook-Signature: v1=<64-lowercase-hex-characters>

<event-id>.<timestamp>.<raw-request-body>

const MAX_AGE_SECONDS = 5 * 60;

function decodeHex(value: string): Uint8Array | null {
  if (!/^[a-f0-9]{64}$/.test(value)) return null;
  return Uint8Array.from(value.match(/../g)!, (pair) => Number.parseInt(pair, 16));
}

export async function verifyPraxaWebhook(input: {
  rawBody: string;
  eventId: string | null;
  timestamp: string | null;
  signature: string | null;
  secret: string;
  nowSeconds?: number;
}): Promise<boolean> {
  const { rawBody, eventId, timestamp, signature, secret } = input;
  if (!eventId || !timestamp || !signature || !secret) return false;

  const seconds = Number(timestamp);
  const now = input.nowSeconds ?? Math.floor(Date.now() / 1_000);
  if (!Number.isSafeInteger(seconds) || Math.abs(now - seconds) > MAX_AGE_SECONDS) {
    return false;
  }

  const digest = signature.startsWith("v1=")
    ? decodeHex(signature.slice(3))
    : null;
  if (!digest) return false;

  const key = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  const signed = `${eventId}.${timestamp}.${rawBody}`;
  return crypto.subtle.verify(
    "HMAC",
    key,
    digest,
    new TextEncoder().encode(signed),
  );
}

​

3. Handle deliveries in your framework

import { verifyPraxaWebhook } from "@/lib/praxa-webhook";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const eventId = request.headers.get("Praxa-Webhook-Id");
  const valid = await verifyPraxaWebhook({
    rawBody,
    eventId,
    timestamp: request.headers.get("Praxa-Webhook-Timestamp"),
    signature: request.headers.get("Praxa-Webhook-Signature"),
    secret: process.env.PRAXA_WEBHOOK_SECRET!,
  });
  if (!valid) return new Response("Invalid signature", { status: 401 });

  const event = JSON.parse(rawBody);
  if (event.apiVersion !== "v1" || event.event_id !== eventId) {
    return new Response("Invalid event", { status: 400 });
  }
  await persistOnce(event.event_id, event.run_id, event.sequence, event);
  return new Response(null, { status: 204 });
}

app.post(
  "/webhooks/praxa",
  express.text({ type: "application/json", limit: "256kb" }),
  async (request, response) => {
    const rawBody = request.body;
    const eventId = request.get("Praxa-Webhook-Id") ?? null;
    const valid = await verifyPraxaWebhook({
      rawBody,
      eventId,
      timestamp: request.get("Praxa-Webhook-Timestamp") ?? null,
      signature: request.get("Praxa-Webhook-Signature") ?? null,
      secret: process.env.PRAXA_WEBHOOK_SECRET!,
    });
    if (!valid) return response.status(401).send("Invalid signature");

    const event = JSON.parse(rawBody);
    await persistOnce(event.event_id, event.run_id, event.sequence, event);
    return response.status(204).end();
  },
);

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const rawBody = await request.text();
    const eventId = request.headers.get("Praxa-Webhook-Id");
    const valid = await verifyPraxaWebhook({
      rawBody,
      eventId,
      timestamp: request.headers.get("Praxa-Webhook-Timestamp"),
      signature: request.headers.get("Praxa-Webhook-Signature"),
      secret: env.PRAXA_WEBHOOK_SECRET,
    });
    if (!valid) return new Response("Invalid signature", { status: 401 });

    const event = JSON.parse(rawBody);
    await persistOnce(env.DB, event.event_id, event.run_id, event.sequence, event);
    return new Response(null, { status: 204 });
  },
};

​

4. Test the signature locally

import { strict as assert } from "node:assert";
import { verifyPraxaWebhook } from "./lib/praxa-webhook.js";

const secret = "praxa_whsec_test_only";
const eventId = "event-1";
const timestamp = "1786651200";
const rawBody = '{"apiVersion":"v1","event_id":"event-1"}';
const key = await crypto.subtle.importKey(
  "raw",
  new TextEncoder().encode(secret),
  { name: "HMAC", hash: "SHA-256" },
  false,
  ["sign"],
);
const bytes = await crypto.subtle.sign(
  "HMAC",
  key,
  new TextEncoder().encode(`${eventId}.${timestamp}.${rawBody}`),
);
const signature = `v1=${[...new Uint8Array(bytes)]
  .map((byte) => byte.toString(16).padStart(2, "0"))
  .join("")}`;

assert.equal(await verifyPraxaWebhook({
  rawBody,
  eventId,
  timestamp,
  signature,
  secret,
  nowSeconds: Number(timestamp),
}), true);
assert.equal(await verifyPraxaWebhook({
  rawBody: `${rawBody} `,
  eventId,
  timestamp,
  signature,
  secret,
  nowSeconds: Number(timestamp),
}), false);

​

5. Verify production delivery

1. Deploy the HTTPS endpoint and create it in Praxa.
2. Trigger a disposable task whose event filter matches the endpoint.
3. Require a valid signature and matching header/body event_id.
4. Require the handler to persist the event before returning 204.
5. Send the same signed event twice in a controlled test and require one logical effect.
6. Send an expired timestamp and a one-byte body change and require 401.
7. List deliveries with GET /v1/webhook-deliveries and require the expected endpoint and run IDs.
8. Exercise replay only after correcting a failed endpoint; replay must remain idempotent.

​

Troubleshooting

​

Best practices

• Persist identity before I/O and state transitions after durable processing.
• Treat admission, delivery attempt, and cancellation request as non-terminal acknowledgements.
• Verify signatures against the raw body before parsing webhook JSON.
• Deduplicate streams and webhooks using stable event or delivery identity.
• Test disconnect, duplicate, out-of-order, timeout, revocation, and cleanup paths.

​

Optimize for production

• Prefer event-driven updates while retaining bounded polling or readback reconciliation.
• Commit cursors in batches only when that cannot lose acknowledged application work.
• Keep webhook handlers short: verify, persist, acknowledge, then process asynchronously.
• Measure admission-to-terminal time, reconnect rate, duplicate rate, delivery latency, and reconciliation backlog.

​

Cleanup and next steps

1. Cancel or terminally reconcile disposable runs.
2. Disable test webhook endpoints and remove their signing secrets.
3. Delete synthetic inbox, cursor, and delivery records after assertions.
4. Revoke disposable credentials and keep only redacted lifecycle evidence.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?