# Register a webhook endpoint.

> Koidog POSTs matching timeline events to `url` (https, not a private address).
> https://koi.dog/docs/api/webhooks/create-webhook/

`POST /api/v1/webhooks` · Scope: `config`

The answer carries the signing secret once. Each delivery has `Koidog-Timestamp` and `Koidog-Signature: v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">`. A failed delivery is retried for about 21 hours. Koidog switches an endpoint off after 50 failed attempts in a row, or after 24 hours in which every attempt failed, with a `webhook.disabled` event; `PATCH /webhooks/{id}` with `enabled: true` switches it on again. When an API key calls it, the timeline records who did what and the outcome. No path or query parameters.

## Headers.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` | no | Makes a retry safe: the same key with the same request returns the first answer and does nothing else. |

## Body.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | yes | Where deliveries are POSTed: https, and not a private address. At most 2000 characters. A URL. |
| `description` | `string` | no | A note for you; Koidog does not use it. At most 200 characters. Default empty. |
| `events` | `array` | yes | Which events to send. Each entry is `*` (every event), an event kind such as `run.started`, or a prefix ending in `.*` that matches at least one kind, such as `run.*`. `webhook.test` is also taken. Anything else is refused with `422 validation_failed`. 1 to 50 items. |
| `projectId` | `string \| null` | no | Only events of this project's crews. Events that belong to no crew are then not sent. At least 5 characters. Default `null`. |
| `enabled` | `boolean` | no | Off: the endpoint is saved but nothing is sent. Default `true`. |

## Response.

201 Created: a JSON object. The example has placeholder values.

- **422 validation_failed**: The body does not match its schema; each problem is in `details`.

## Request.

```sh
curl -X POST https://app.koi.dog/api/v1/webhooks \
    -H "Authorization: Bearer $KOIDOG_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/koidog-webhook",
      "events": [
        "run.*",
        "crew.*"
      ]
    }'
```

```js
const res = await fetch("https://app.koi.dog/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOIDOG_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/koidog-webhook",
    events: [
      "run.*",
      "crew.*",
    ],
  }),
});
console.log(await res.json());
```

```python
import os
import uuid

import requests

r = requests.post(
    "https://app.koi.dog/api/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['KOIDOG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "url": "https://example.com/koidog-webhook",
        "events": [
            "run.*",
            "crew.*",
        ],
    },
)
r.raise_for_status()
print(r.json())
```

## Response example.

```json
{
  "webhook": {
    "id": "string",
    "url": "string",
    "urlShortened": false,
    "description": "string",
    "events": [],
    "projectId": "string",
    …
  },
  "secret": "string"
}
```
