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

# Create a webhook endpoint

> Register an HTTPS endpoint for integration webhook events. The signing secret is returned once, in this response only. A team can have 10 endpoints.

Creates an endpoint for the team. The signing secret is returned **once**, in
this response only. Store it to [verify signatures](https://docs.qwairy.co/developers/integration-webhooks/verify-signatures.md).
A team can have at most 10 endpoints.

Integration webhooks require an active Business, Agency Business or Enterprise plan. Changing an endpoint also requires an API token with write access enabled by an Owner or Manager. See [Integration webhooks](https://docs.qwairy.co/developers/integration-webhooks/overview.md) and [Writing data](https://docs.qwairy.co/developers/writing-data.md).

**Authorization** `string` *required*

Bearer token for your team.

**Idempotency-Key** `string` *required*

Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.

**url** `string` *required*

Public HTTPS URL, at most 2048 characters. Redirects are not followed.

**events** `string[]` *required*

At least one [event type](https://docs.qwairy.co/developers/integration-webhooks/events.md): `run.completed`,
`run.failed`, `run.cancelled`, `pitch_audit.completed`, `pitch_audit.failed`,
`site_audit.completed`, `prompt_suggestions.ready`, `prompt_suggestions.failed`
or `webhook.test`.

**description** `string`

Free description, at most 200 characters.

**brandIds** `string[]`

Limit the endpoint to these workspaces, at most 100. Omit it or send an empty
array to receive the events of every workspace of the team.

**enabled** `boolean` (default: true)

Whether the endpoint receives events right away.

## Response

Returns `201` with `Location`, `ETag` and the endpoint, plus the `secret`.

**secret** `string`

Signing secret. Shown once; it cannot be read again. Rotate it with
[Rotate the signing secret](https://docs.qwairy.co/developers/endpoints/webhooks/rotate-secret.md) if you lose it.

The other fields are described in [List webhook endpoints](https://docs.qwairy.co/developers/endpoints/webhooks/list.md).

## Synthetic request and response

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/webhooks" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: webhook-endpoint-001" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/qwairy","description":"Production receiver","events":["run.completed","run.failed"]}'
```

```json theme={null}
{
  "id": "eeeeeeee-0000-4000-8000-000000000000",
  "url": "https://hooks.example.com/qwairy",
  "description": "Production receiver",
  "events": ["run.completed", "run.failed"],
  "brandIds": [],
  "enabled": true,
  "disabledReason": null,
  "failingSince": null,
  "previousSecretExpiresAt": null,
  "version": 0,
  "createdAt": "2026-10-12T09:00:00.000Z",
  "updatedAt": "2026-10-12T09:00:00.000Z",
  "secret": "synthetic-signing-secret"
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | Invalid URL, unknown event, or a value out of range |
| `409` | `CONFLICT` | The request conflicts with the current endpoints, for example the limit of 10 endpoints |
| `409` | `IDEMPOTENCY_CONFLICT` | The key was reused with a different body |

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency and server errors. A token without write access returns `403 API_KEY_READ_ONLY`. On `429`, honor `Retry-After`. If the write limiter is unavailable or writes are suspended, the request returns `503 SERVICE_UNAVAILABLE` and nothing changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.