> 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/register-a-webhook.md).

# Register a webhook

Registers a webhook for one event type. `event_type`, `target_url` and `retry_countdown_config` are required; the webhook is active straight away. The requesting account becomes its owner.

The account may not already have a webhook for the same `event_type` and `target_url` — inactive ones included; reactivate that one instead.

````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."}},"schemas":{"WebhookRequest":{"type":"object","description":"The data to register or fully update a webhook.","required":["event_type","target_url","retry_countdown_config"],"properties":{"event_type":{"type":"string","maxLength":124,"description":"The event type to subscribe to; one of the values returned by `GET /whisperer/hooks/registry/`."},"target_url":{"type":"string","maxLength":255,"description":"The URL events are posted to."},"retry_countdown_config":{"$ref":"#/components/schemas/WebhookRetryCountdownConfig"},"is_active":{"type":"boolean","default":true,"description":"Whether the webhook receives events."},"secret_key":{"type":["string","null"],"maxLength":124,"description":"When set, every request carries an `X-Whisperer-Signature` header computed with this key."},"additional_headers":{"type":"object","additionalProperties":{"type":"string"},"default":{},"description":"Extra HTTP headers sent with every request."},"config":{"type":"object","additionalProperties":true,"default":{},"description":"Delivery options. `{\"auth\": {\"auth_type\": \"basic\", \"username\": \"...\", \"password\": \"...\"}}` enables HTTP basic authentication."},"callback":{"type":["string","null"],"maxLength":64,"description":"Reserved for platform integrations; leave `null`."}}},"WebhookRetryCountdownConfig":{"type":"object","description":"The wait between retries of a failed delivery. `kwargs` depends on `choice`; see **Retry Countdown** in the **Webhooks** section.","required":["choice","kwargs"],"properties":{"choice":{"type":"string","enum":["fixed","linear","exponential","random"],"description":"The retry strategy."},"kwargs":{"type":"object","additionalProperties":true,"description":"The strategy's parameters."}}},"Webhook":{"type":"object","description":"A webhook subscription.","properties":{"id":{"type":"integer","description":"The unique identifier of the webhook."},"retry_countdown_config":{"$ref":"#/components/schemas/WebhookRetryCountdownConfig"},"created_date":{"type":"string","format":"date-time","description":"When the webhook was registered."},"modified_date":{"type":"string","format":"date-time","description":"When the webhook was last modified."},"target_url":{"type":"string","maxLength":255,"description":"The URL events are posted to."},"is_active":{"type":"boolean","description":"Whether the webhook receives events."},"secret_key":{"type":["string","null"],"maxLength":124,"description":"The key requests are signed with, returned as stored; `null` when requests are not signed."},"event_type":{"type":"string","maxLength":124,"description":"The event type the webhook subscribes to."},"callback":{"type":["string","null"],"maxLength":64,"description":"Reserved for platform integrations; normally `null`."},"additional_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra HTTP headers sent with every request."},"config":{"type":"object","additionalProperties":true,"description":"Delivery options, such as `auth` for HTTP basic authentication."}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"WebhookAlreadyRegisteredError":{"type":"object","description":"Returned when a webhook for the same event type and target URL already exists.","properties":{"code":{"type":"string","description":"The error code, `webhook_100_2`."},"en":{"type":"string","description":"The error message."}}}},"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"}}}},"WebhookAlreadyRegistered":{"description":"The account already has a webhook, active or inactive, for this `event_type` and `target_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAlreadyRegisteredError"}}}}}},"paths":{"/whisperer/hooks/":{"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Register a webhook","description":"Registers a webhook for one event type. `event_type`, `target_url` and `retry_countdown_config` are required; the webhook is active straight away. The requesting account becomes its owner.\n\nThe account may not already have a webhook for the same `event_type` and `target_url` — inactive ones included; reactivate that one instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}}},"responses":{"201":{"description":"The registered webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"The request contains invalid or missing data — for example an `event_type` that is not in the registry or an unknown retry strategy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/WebhookAlreadyRegistered"}}}}}}
````


---

# 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/register-a-webhook.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.
