# Create a webhook endpoint

`POST /api/v1/webhooks`

Subscribes an https URL to one or more event types. The response carries the signing secret ONCE — store it now, it cannot be read back, only rotated. At most 10 endpoints per organization. Requires the "webhooks:manage" scope.

Scope: `webhooks:manage`
Idempotency-Key: optional

## Parameters

- `Idempotency-Key` (header, string) — Optional. A unique key, 8-200 characters. Retrying with the same key replays the first response verbatim instead of acting twice.

## Request body

- `url` (string, required) — The https URL to POST events to. Must be a public address — private and loopback addresses are rejected. Maximum 2048 characters.
- `events` ("booking.created" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "customer.created" | "customer.updated" | "gift_card.issued" | "gift_card.redeemed"[], required) — Event types to subscribe to. At least one. "ping" cannot be subscribed to — test deliveries are sent regardless of this list.
- `description` (string) — A note to yourself about what this endpoint is for.

## Responses

- `200` — The endpoint, with its signing secret. Returned when nothing new was created — the resource already existed, or this is a replay of an earlier request with the same Idempotency-Key.
- `201` — The endpoint, with its signing secret.
- `400` — Invalid request — codes "validation_failed" or, on an endpoint that requires one, "idempotency_key_required".
- `401` — Missing, invalid, revoked or expired API key — codes "api_key_missing", "api_key_invalid", "api_key_revoked", "api_key_expired".
- `403` — The API app is off, the plan does not include the API, or the key lacks the required scope — codes "app_not_enabled", "plan_upgrade_required", "insufficient_scope" (the last carries "required_scope").
- `422` — The request was understood but cannot be fulfilled as asked — codes "validation_failed" or "idempotency_key_reused" (the same Idempotency-Key was already used with a different body).
- `429` — Rate limit exceeded — code "rate_limited". See the x-ratelimit-* headers.
- `500` — Something went wrong on our side — code "internal_error".

## Response `200`

- `id` (string, required) — Awrora id (UUID) for the endpoint.
- `url` (string, required) — The https URL deliveries are POSTed to.
- `description` (string | null, required) — Free-text note, or null.
- `events` (string[], required) — The event types this endpoint receives. Test deliveries ignore this list.
- `status` ("enabled" | "disabled" | "auto_disabled", required) — enabled = receiving; disabled = turned off by the merchant; auto_disabled = turned off by Awrora after 72 hours without a successful delivery. PATCH status back to "enabled" to resume — that also resets the failure counter.
- `source` ("admin" | "api", required) — "api" when created through this API, "admin" when created in Awrora.
- `consecutive_failures` (integer, required) — Failed deliveries in a row. Reset to zero by the next success.
- `last_success_at` (string | null, required) — ISO 8601 with offset, or null.
- `last_failure_at` (string | null, required) — ISO 8601 with offset, or null.
- `created_at` (string, required) — ISO 8601 timestamp with offset.
- `updated_at` (string, required) — ISO 8601 timestamp with offset.
- `secret` (string, required) — The signing secret ("whsec_…"). Shown ONCE, here. Store it now — it cannot be read back, only rotated.

## Example

```bash
curl -X POST "https://your-site.awrora.app/api/v1/webhooks" \
  -H "Authorization: Bearer $AWRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/awrora",
  "events": [
    "booking.created"
  ],
  "description": "string"
}'
```