> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/webhooks/list-event-types.md).

# List event types

Returns the event types a webhook can subscribe to, as a plain (unpaginated) array of strings.

````json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Administrative endpoints for **webhooks** — subscriptions that make the platform `POST` an event to an external URL whenever that event occurs, for example when a user registers or a basket offer is updated.\n\n## Core Capabilities\n\n**1. Event Type Registry**\n* List the event types a webhook can subscribe to with `GET /whisperer/hooks/registry/`.\n\n**2. Webhook Management**\n* Register a webhook for one event type and target URL, retrieve and list webhooks, fully (`PUT`) or partially (`PATCH`) update them, and deactivate them.\n\n**3. Delivery History**\n* Every delivery attempt is recorded as a webhook event — see **Webhook Events**.\n* Resend an undelivered event with `POST /whisperer/hook_events/{id}/retry/`.\n\n## Visibility\n\nA webhook belongs to the account that registered or last updated it. Superusers see every webhook; any other account sees only its own. Through the Omnitron remote proxy, that account is the Omnitron integration account of the channel. Creating, updating and deleting webhooks additionally requires the matching model permission; without it the request is refused with `403`.\n\n## Event Types\n\n| `event_type` | `payload` |\n|--------------|-----------|\n| `user_registered`, `user_logged_in`, `user_updated` | The user. |\n| `conversation_replied` | The conversation. |\n| `basket_offer_created`, `basket_offer_updated` | The basket offer. |\n\n`GET /whisperer/hooks/registry/` is authoritative: the list depends on the modules installed on the channel. An event type reaches webhooks only when the channel publishes it for asynchronous delivery through its event message definitions; subscribing alone does not make the platform emit it.\n\n## Webhook Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | integer | The unique identifier of the webhook. Read-only. |\n| `event_type` | string, up to 124 characters | The event the webhook subscribes to. Must be one of the registry's event types. Required on create and full update. |\n| `target_url` | string, up to 255 characters | The URL the event is posted to. Required on create and full update. |\n| `is_active` | boolean, default `true` | Only active webhooks receive events. |\n| `secret_key` | string or `null`, up to 124 characters | When set, every request is signed with it (see **Delivery**). Returned as stored in responses. |\n| `retry_countdown_config` | object | How long to wait between retries of a failed delivery (see **Retry Countdown**). Required on create and full update. |\n| `additional_headers` | object, default `{}` | Extra HTTP headers sent with every request, as header name to value. |\n| `config` | object, default `{}` | Delivery options. `auth` enables HTTP basic authentication: `{\"auth\": {\"auth_type\": \"basic\", \"username\": \"...\", \"password\": \"...\"}}`. Other keys are stored but ignored. |\n| `callback` | string or `null`, up to 64 characters | Reserved for platform integrations: the import path of a server-side function run after each delivery. Leave it `null`; an unknown path makes deliveries fail. |\n| `created_date`, `modified_date` | date-time | Read-only timestamps. |\n\nThe same account can register a given `event_type` and `target_url` pair only once.\n\n## Retry Countdown\n\n`retry_countdown_config` is `{\"choice\": \"<strategy>\", \"kwargs\": {...}}`. `n` is the number of retries already made, starting at `0`.\n\n| `choice` | `kwargs` | Wait before retry `n` (seconds) |\n|----------|----------|----------------------------------|\n| `fixed` | `seconds` (integer ≥ 0, required) | `seconds` |\n| `linear` | `base` (integer ≥ 0, required), `limit` (integer ≥ 0 or `null`) | `base × n`, capped at `limit` |\n| `exponential` | `base` (integer ≥ 0, required), `factor` (integer ≥ 1, default `1`), `limit` (integer ≥ 0 or `null`) | `base^n × factor`, capped at `limit` |\n| `random` | `min_value`, `max_value` (integers ≥ 0, both required; `max_value` must be greater) | A random value between the two, inclusive |\n\n## Delivery\n\nEach event is sent as `POST` to `target_url` with a JSON body:\n\n```json\n{\n  \"event\": {\"type\": \"user_registered\", \"uuid\": \"9f1c2e0b7d4a4b6c8e2f1a3b5c7d9e0f\"},\n  \"payload\": {\"pk\": 1001, \"email\": \"jane.doe@example.com\"}\n}\n```\n\n* Headers: `Content-Type: application/json`, `X-Whisperer-Event: <event_type>`, any `additional_headers`, and — when `secret_key` is set — `X-Whisperer-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw request body keyed with `secret_key`.\n* A `2xx` response counts as delivered. Any other status, a network error or a timeout counts as a failure, and the delivery is retried up to 10 times, waiting as `retry_countdown_config` dictates. Every attempt is recorded on the same webhook event.\n\n## Filtering & Ordering\n\n| Parameter | Match |\n|-----------|-------|\n| `event_type` | Exact, case-insensitive |\n| `target_url` | Exact, case-insensitive |\n| `is_active` | `true` or `false` |\n\nUse the `sort` parameter to order the results by any webhook field (for example `sort=-created_date`). Without `sort` the order is not guaranteed, so pass one when paging through results.\n\n## Deleting a Webhook\n\n`DELETE` does not remove the webhook: it sets `is_active` to `false`, keeps its delivery history, and the webhook is still returned by list and retrieve. Reactivate it with `PATCH` and `{\"is_active\": true}`.\n\n## Dynamic Settings & Environment Variables\n\nNo dynamic settings affect these endpoints.\n\n**Environment variables / Django settings:**\n\n| Setting | Default | Effect |\n|---------|---------|--------|\n| `WHISPERER_REQUEST_TIMEOUT` | `10` | Seconds to wait for the target URL to answer before the attempt counts as a failure. |"}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"responses":{"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}}},"paths":{"/whisperer/hooks/registry/":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEventTypes","summary":"List event types","description":"Returns the event types a webhook can subscribe to, as a plain (unpaginated) array of strings.","responses":{"200":{"description":"The registered event types.","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/webhooks/list-event-types.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
