Skip to main content
POST
Create a webhook endpoint
Create a Praxa webhook endpoint, capture its one-time signing secret, and verify signed delivery with least-privilege scopes.
Availability: Partner preview. Required scopes: runs:write, runs:read.

Authenticate safely

Create a disposable personal workspace API key with exactly runs:write and runs:read. Send it as Authorization: Bearer $PRAXA_API_KEY. A Gateway OAuth token, Supabase JWT, provider credential, or organization memory key is not interchangeable with this key. The hosted playground sends the credential from your browser session to the documented API through the configured playground proxy. Use test data, never share the key, and revoke it when the check ends.

Request fields

string
required
url request field.
array<run.accepted | run.started | run.progress | approval.required | approval.resolved | run.completed | run.failed | run.cancelled>
required
event_types request field.
string
description request field.

Runnable request examples

What success means

A 201 response creates the endpoint and returns its signing secret exactly once.

Successful response

201 — Endpoint metadata and its one-time signing secret.
object
required
endpoint response field.
string
required
Returned only when the endpoint is created.

Handle failures

Example problem

Verify the result

  1. Store the secret in a secret manager immediately.
  2. Trigger one disposable matching event and verify its raw-body signature.
  3. List the endpoint and confirm the secret is no longer returned.

Retry, cleanup, and production use

  • Treat 401, 403, and 409 as authority or state signals, not generic retry prompts.
  • For 429 or retryable 5xx responses, follow server retry guidance and keep a bounded attempt budget.
  • Move the request into a trusted application backend before production; never ship the Praxa key in browser or mobile code.
  • Revoke the disposable key, disable test webhooks, and erase disposable candidate data after validation.
Continue with API authentication, the failure and retry guide, and the end-to-end coverage matrix.
Last modified on August 14, 2026