Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/open-webhook-portal.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Open the webhook portal

Returns a short-lived login url to your account's hosted webhook portal, where you add endpoint URLs, select event types, copy whsec_ signing secrets, and inspect deliveries.

POST https://api.diffio.ai/v2/webhooks/portal

  • Key scope: webhooks:write
  • Auth header:Authorization: Bearer <apiKey>
  • Body: None

Request

Call with your API key and no request body (or {}); omit Diffio-End-User.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoNot accepted on this account-wide endpoint; sending Diffio-End-User returns 403 (permission_denied).

Request

import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

portal = client.webhooks.portal()

Response

Returns a short-lived portal url and the list of supported event_types.

Success: 200OK.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "webhook_portal".webhook_portal
#urlstringAlwaysShort-lived login URL to the hosted webhook portal; open it immediately and request a fresh link each session.
#event_typesarrayAlwaysSorted list of all 10 webhook event types emitted for the account.

Response 200OK.

Successful response
{
  "object": "webhook_portal",
  "url": "https://app.svix.com/login#key=REDACTED",
  "event_types": [
    "export.failed",
    "export.ready",
    "generation.completed",
    "generation.failed",
    "generation.stems_failed",
    "generation.stems_ready",
    "project.failed",
    "project.ready",
    "transcript_assistant_turn.completed",
    "transcript_assistant_turn.failed"
  ]
}

Return codes

  • 200OK.Returns a short-lived webhook portal url and event_types.
  • 400Bad request.Malformed JSON body, or Diffio-End-User exceeds 128 characters. invalid_jsoninvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or read-only (no webhooks:write), or the request sent Diffio-End-User. permission_denied
  • 502Bad gateway.Upstream webhook portal error. internal_error
  • 503Service unavailable.Webhook service is not configured or temporarily unavailable (code unavailable).
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. HTTP method not supported on this path; check the Allow header (code method_not_allowed).

Example error response

Errors are JSON: an error object with code, message and request_id. An unrecognized key returns 401Unauthorized: the API key is missing or invalid.:

Error response
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}

Notes

  • The first call enables webhook events for your account; from then on state changes across all keys and end users emit events (each payload's data.end_user identifies the end user).
  • Every delivery is signed with Svix headers (svix-id, svix-timestamp, svix-signature) using your endpoint's whsec_ secret; verify the raw body with client.webhooks.verify_signature(...) in Python or client.webhooks.verifySignature(...) in Node.js.
  • Event id (evt_...) stays identical across retries for idempotency, and data carries thin resource identifiers (id, project_id, status, end_user); fetch the resource with GET when you need full fields. See Webhooks.

Report an issue with this page