Receive webhooks

Status: Production partner preview for admitted personal tenants. Projection starts with events created after activation and does not backfill earlier task events.

Webhooks let your server receive durable run progress without holding an SSE connection open. Praxa signs every request, retries failed deliveries, and may deliver the same event more than once or out of order. Your handler must verify the raw request, persist each event idempotently, and order changes within each run.

1. Register an endpoint

The signed-in developer portal uses POST /api/platform/webhooks. The bearer SDK contract uses this active partner-preview operation:

This operation is available only to keys issued to admitted personal tenants. It is not generally available.

POST /v1/webhooks
Authorization: Bearer praxa_sk_<64 lowercase hex characters>
Content-Type: application/json

{
  "url": "https://your-service.example.com/webhooks/praxa",
  "event_types": ["approval.required", "run.completed", "run.failed"]
}

The gateway requires runs:write. The backend reauthorizes both runs:read and runs:write, so the key must carry both scopes. The response status is 201. The response includes signing_secret once. Store it immediately in your secret manager; Praxa will not show it again.

{
  "endpoint": {
    "apiVersion": "v1",
    "id": "73f700a8-5367-4c78-9d13-8b60c9bb9374",
    "url": "https://your-service.example.com/webhooks/praxa",
    "event_types": ["approval.required", "run.completed", "run.failed"],
    "status": "active",
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:00:00.000Z"
  },
  "signing_secret": "praxa_whsec_..."
}

The automatic projection migration is forward-only. An endpoint receives matching events created after the production projection migration; creating an endpoint does not backfill earlier run history.

2. Verify the signature before parsing

Every delivery carries:

Praxa-Webhook-Id: <event-id>
Praxa-Webhook-Timestamp: <unix-timestamp>
Praxa-Webhook-Signature: v1=<lowercase hex digest>

Praxa computes HMAC-SHA-256 over:

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

Verify the exact raw bytes. Parsing and re-serializing JSON first can change whitespace or key order and invalidate the signature.

const REPLAY_WINDOW_SECONDS = 5 * 60;

function hexBytes(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() / 1000);
  if (!Number.isSafeInteger(seconds)) return false;
  if (Math.abs(now - seconds) > REPLAY_WINDOW_SECONDS) return false;

  const digest = signature.startsWith("v1=")
    ? hexBytes(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),
  );
}

Use it before JSON.parse:

export async function handlePraxaWebhook(request: Request): 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: 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 persistOnceAndQueue(event.event_id, event.run_id, event.sequence, event);
  return new Response(null, { status: 204 });
}

persistOnceAndQueue should atomically insert event_id under a unique constraint and enqueue any slower work. Return 2xx only after that transaction commits. If the id already exists, acknowledge the duplicate without repeating its effects.

3. Deduplicate and order per run

Praxa provides at-least-once delivery. Retries and manual replay preserve the same immutable event_id, so use that as the deduplication key. Delivery order is not guaranteed. A retry of sequence 11 can arrive after sequence 12. Use (run_id, sequence) to process or reconstruct one run’s ordered history:

type PraxaWebhookEvent = {
  event_id: string;
  run_id: string;
  sequence: number;
};

function compareWithinRun(a: PraxaWebhookEvent, b: PraxaWebhookEvent): number {
  if (a.run_id !== b.run_id) throw new Error("events belong to different runs");
  return a.sequence - b.sequence;
}

Do not treat sequence as global, and do not use HTTP arrival order as run state. You may receive a later event before an earlier one.

4. Parse the strict v1 body

The body contains exactly seven top-level fields:

{
  "apiVersion": "v1",
  "event_id": "864d6901-0de1-4fcf-9c9d-1a1f9d60cb4a",
  "created_at": "2026-08-01T12:45:18.430Z",
  "run_id": "3b7e72a9-8607-4e99-9acc-71b81cf7742b",
  "sequence": 12,
  "type": "run.progress",
  "data": {
    "status": "running"
  }
}

The data object is strict and depends on type. Reconciliation notifications are run.progress with exactly { "status": "running" }. A permanently unknown committing outcome is:

{
  "apiVersion": "v1",
  "event_id": "1d530fb7-ed06-46d4-b24d-345210623bc2",
  "created_at": "2026-08-01T12:49:20.101Z",
  "run_id": "3b7e72a9-8607-4e99-9acc-71b81cf7742b",
  "sequence": 13,
  "type": "run.failed",
  "data": {
    "status": "failed",
    "error_code": "run_outcome_unknown"
  }
}

Do not automatically retry or resubmit that run. See Webhooks for every type-specific shape.

5. Fetch the approval before rendering it

An approval.required webhook is a notification, not the approval presentation. Its data contains only:

{
  "status": "waiting_approval",
  "action_digest": "5f1d2c9a4e7b0f3d6c8a1b2e9f4d7c0a3b6e9f2c5a8d1b4e7f0c3a6d9b2e5f8c"
}

Fetch GET /v1/runs/:id, require pendingApproval, and verify its digest equals the webhook digest. Only then render the exact pendingApproval.summary and allow a human to approve or deny. If the run no longer exposes that exact pending approval, fail closed and acknowledge the webhook without showing active decision controls. Submit the public decision with the unchanged digest:

POST /v1/runs/{runId}/approve
Authorization: Bearer praxa_sk_<64 lowercase hex characters>
Content-Type: application/json

{
  "action_digest": "5f1d2c9a4e7b0f3d6c8a1b2e9f4d7c0a3b6e9f2c5a8d1b4e7f0c3a6d9b2e5f8c",
  "decision": "approve"
}

The public request accepts approve or deny. The later approval.resolved.data.decision webhook deliberately preserves the internal event values approved or denied. Do not send those past-tense values in the public approval request.

6. Understand retries and dead letters

Return 2xx after durable acceptance, then process slow work asynchronously.
Timeouts, 408, 409, 425, 429, and 5xx responses are retryable.
Praxa makes at most five attempts, delayed by 30 seconds, 5 minutes, 30 minutes, and 2 hours.
Other 4xx responses and refused or unsafe redirects fail permanently.
A delivery that exhausts retries enters dead_letter. Inspect it and use the idempotent replay action after correcting your endpoint.

Use the active bearer management route to list delivery records with a key carrying runs:read:

GET /v1/webhook-deliveries?endpoint_id=73f700a8-5367-4c78-9d13-8b60c9bb9374&status=dead_letter&limit=50
Authorization: Bearer praxa_sk_<64 lowercase hex characters>

You can filter by endpoint_id, run_id, or status, page with cursor, and set limit from 1 to 100. The default is 50. The response status is 200, and the strict list contains apiVersion, data, and optional nextCursor. Replay a corrected dead-letter delivery by sending an exact empty object:

POST /v1/webhook-deliveries/{deliveryId}/replay
Authorization: Bearer praxa_sk_<64 lowercase hex characters>
Content-Type: application/json

{}

The gateway checks runs:write, while the backend requires both runs:read and runs:write. A successful replay returns 202 and the created or idempotently reused delivery record.

Production evidence

A production canary created an endpoint, received a delivery, and verified its HMAC over the exact raw body. Retry, dead-letter, eligible replay, and redirect safety remain separate operational canaries. Build idempotent handling as documented even when a particular retry path has not been forced in a live canary.

Next steps

Build the human decision flow with Build an approval UI.
Review the full payload, signing, activation, and endpoint constraints in Webhooks.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Receive webhooks

1. Register an endpoint

2. Verify the signature before parsing

3. Deduplicate and order per run

4. Parse the strict v1 body

5. Fetch the approval before rendering it

6. Understand retries and dead letters

Production evidence

Next steps

​1. Register an endpoint

​2. Verify the signature before parsing

​3. Deduplicate and order per run

​4. Parse the strict v1 body

​5. Fetch the approval before rendering it

​6. Understand retries and dead letters

​Production evidence

​Next steps

1. Register an endpoint

2. Verify the signature before parsing

3. Deduplicate and order per run

4. Parse the strict v1 body

5. Fetch the approval before rendering it

6. Understand retries and dead letters

Production evidence

Next steps