> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/open-webhook-portal/.

# 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Not accepted on this account-wide endpoint; sending `Diffio-End-User` returns `403` (`permission_denied`). |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

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

portal = client.webhooks.portal()
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const portal = await client.webhooks.portal()
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/webhooks/portal" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

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

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"webhook_portal"`. |
| `url` | string | Always | Short-lived login URL to the hosted webhook portal; open it immediately and request a fresh link each session. |
| `event_types` | array | Always | Sorted list of all 10 webhook event types emitted for the account. |

## Example response (200)

**Successful response**

```json
{
  "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

- `200` Returns a short-lived webhook portal `url` and `event_types`.
- `400` Malformed JSON body, or `Diffio-End-User` exceeds 128 characters. [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json) [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or read-only (no `webhooks:write`), or the request sent `Diffio-End-User`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `502` Upstream webhook portal error. [`internal_error`](https://diffio.ai/docs/api-reference/errors/#internal_error)
- `503` Webhook service is not configured or temporarily unavailable (code unavailable).
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` 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 `401`:

**Error response**

```json
{
  "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](https://diffio.ai/docs/developers/webhooks/).

## Related pages

- Previous: [Get usage](https://diffio.ai/docs/api-reference/usage-summary/): Report generation counts, billable seconds, and USD list-price usage in total and by model.
- Next: [Webhooks guide](https://diffio.ai/docs/developers/webhooks/): Creating an endpoint and verifying signed events.

- [API reference](https://diffio.ai/docs/api-reference/introduction/): Base URL, authentication, errors and every endpoint.
