> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook subscription

> Copy into Cursor/Claude/Copilot to scaffold a POST /v1/webhooks integration.

Drop this prompt into your AI coding assistant. It already includes the contract, auth, and error envelope so the generated code matches the production API.

<CodeGroup>
  ```text Prompt theme={null}
  You are integrating Telepatia Synapse Public API.

  Endpoint: POST /v1/webhooks
  Base URL: https://scribe-api.telepatia.ai
  Auth: Authorization: Bearer ${SYNAPSE_API_KEY}

  Request:
  - url [body]: string (required, format=uri, minLength=1, maxLength=2083) — https endpoint that will receive event POSTs.
  - name [body]: string (optional, maxLength=100) — Optional human-readable label to identify this webhook in lists/UI. Trimmed server-side; a blank value stores no name.
  - events [body]: array<WebhookEventName> (optional) — Event types to subscribe to (at least one). Preferred over `event`.
  - event [body]: string (optional, enum: scribe_session.created, scribe_session.completed, scribe_session.error, scribe_session.updated, scribe_session.cancelled, scribe_session.deleted) — Webhook event types exposed to API clients.

  Mirrors `SynapseWebhookEventType` enum in datalayer (camelCase) but
  rendered to clients as snake_case dotted strings (closer to Stripe
  convention and easier to grep in caller logs).

  Success 200:
  - id: string
  - url: string
  - name?: string
  - events: array<WebhookEventName>
  - event?: string
  - isActive: boolean
  - signingSecretPrefix?: string
  - signingSecretVersion?: integer
  - createdAt?: string
  - updatedAt?: string
  - deletedAt?: string
  - signingSecret: string

  Errors (envelope: { error: { type, code, message, param? } }):
  - 400: parameter_missing, parameter_invalid, account_invalid
  - 401: authentication_required
  - 403: permission_denied
  - 503: service_unavailable

  Generate code in the language of the current file that:
  1. Reads SYNAPSE_API_KEY from env (do not hardcode it).
  2. Calls the endpoint with typed request and response.
  3. Maps the error envelope to typed exceptions per status code.
  4. Adds one happy-path test using the Bearer token.
  ```

  ```bash curl theme={null}
  curl -X POST https://scribe-api.telepatia.ai/v1/webhooks \
    -H "Authorization: Bearer $SYNAPSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "events": [
      "scribe_session.created",
      "scribe_session.completed",
      "scribe_session.error"
    ],
    "name": "Scribe prod webhook",
    "url": "https://example.com/webhooks/scribe"
  }'
  ```
</CodeGroup>