Webhooks

Status: Developer preview — contract-stable per @nexislabs/ai-platform v1; not yet serving public traffic.

POST /v1/webhooks

​

Confirmed behavior

• Deliveries are HMAC-signed.
• Failed deliveries are retried with exponential backoff.
• Deliveries that exhaust retries land in a dead-letter state.
• Signing secrets are rotatable per tenant.

​

Authentication

​

Request body

Gap. Neither source publishes field-level names for the registration request or response. The table below is this reference’s best-effort, clearly-flagged reconstruction from the confirmed behavior above and conventional webhook-registration shape — not a confirmed contract. Verify against the actual implementation before relying on exact field names.

​

Response (illustrative — not confirmed)

​

Delivery payload

​

What is genuinely unresolved

• Exact request/response field names for POST /v1/webhooks.
• The HMAC signature scheme (header name, algorithm, canonicalization).
• The retry schedule (attempt count, backoff base/cap) and how a dead-lettered delivery is surfaced to the tenant.
• Secret-rotation mechanics (single active secret vs. overlap window).

​

Example

curl https://api.praxa.io/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer praxa_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/praxa",
    "events": ["response.final", "approval.required"]
  }'

​

TypeScript

// Field names are illustrative — see the Gap note above.
type WebhookRegistration = {
  url: string;
  events?: string[];
};

type WebhookEndpoint = {
  id: string;
  secret: string;
} & Record<string, unknown>;

async function registerWebhook(
  registration: WebhookRegistration,
  apiKey: string,
): Promise<WebhookEndpoint> {
  const res = await fetch("https://api.praxa.io/v1/webhooks", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(registration),
  });
  if (!res.ok) throw new Error(`webhook registration failed: ${res.status}`);
  return res.json();
}