# Create webhook

> Registers a URL that receives task events as they happen, so you do not have to poll. Deliveries are signed (Standard Webhooks); the signing secret is returned here and nowhere else.

Registers an endpoint that Mynth POSTs to when a task settles. Deliveries are
signed with the `whsec_` secret in this response, following
[Standard Webhooks](https://www.standardwebhooks.com). The API returns it only here,
so store it now. The dashboard also shows it on the endpoint's page.

[Webhooks](https://mynth.io/docs/concepts/webhooks.md) has the signature check, events, and
sources. [Webhook payloads](https://mynth.io/docs/api-reference/webhook-payloads.md) has the body
of each event.

`POST /webhooks`

**Auth:** API key or OAuth token

## Request body

- `enabled` (boolean) — Whether the webhook is enabled. When disabled, no events will be sent to the webhook. Default `true`.
- `url` (required, string) — Receives the events. Must be https and a public host. Example `"https://example.com/hooks/mynth"`.
- `events` (required, string[]) — The events to send. `["all"]` sends every event, including ones added later. `task.completed` and `task.failed` cover every task type. ≥ 1 items.
- `api_key_ids` (string[] | null) — Tasks created with these API keys are sent. Omitted or null: every key, including keys created later. An empty list: no key. ≤ 1000 items.
- `include_session_tasks` (boolean) — Also send tasks created without an API key: playground runs and other signed-in (OAuth) sessions. Tasks the CLI creates carry its API key, so `api_key_ids` decides those. Default `false`.

## Response

### 201 — Webhook created

- `data` (required, object)
  - `id` (required, string)
  - `user_id` (required, string)
  - `enabled` (required, boolean)
  - `url` (required, string)
  - `events` (required, string[])
  - `api_key_ids` (required, string[] | null)
  - `include_session_tasks` (required, boolean)
  - `created_at` (required, string) — format: date-time.
  - `updated_at` (required, string) — format: date-time.
  - `secret` (required, string) — Signs every delivery to this webhook (Standard Webhooks). Returned here and nowhere else in the API. Example `"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"`.

```json
{
  "data": {
    "id": "string",
    "user_id": "string",
    "enabled": false,
    "url": "string",
    "events": [
      "all"
    ],
    "api_key_ids": [
      "string"
    ],
    "include_session_tasks": false,
    "created_at": "string",
    "updated_at": "string",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}
```

### 400 — The request was rejected before anything was queued. `error.message` says what to change. A field that failed the schema, or one the endpoint does not take, is also listed in `error.issues`.

- `error` (required, object)
  - `code` (required, string) — `validation_error` for a body that failed validation, `invalid_json` for one that is not JSON. One of: `"validation_error"`, `"invalid_json"`.
  - `message` (required, string) — Every problem, in one sentence each, led by the field it is about.
  - `issues` (object[]) — One entry per field that failed the schema, and one per field the endpoint does not take.
    - `path` (required, (string | integer)[]) — Where the problem is, e.g. `["inputs", 0, "source"]`. Empty for the body as a whole.
    - `message` (required, string)

```json
{
  "error": {
    "code": "validation_error",
    "message": "count: Too big: expected number to be <=20. colour: Unknown field.",
    "issues": [
      {
        "path": [
          "count"
        ],
        "message": "Too big: expected number to be <=20"
      },
      {
        "path": [
          "colour"
        ],
        "message": "Unknown field."
      }
    ]
  }
}
```

## Request samples

### cURL

```bash
curl -X POST https://api.mynth.io/webhooks \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/mynth",
    "events": [
      "all"
    ]
  }'
```

### JavaScript

```ts
const response = await fetch("https://api.mynth.io/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MYNTH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/hooks/mynth",
    "events": [
      "all"
    ]
  }),
});

const { data } = await response.json();
```

The full schema for this endpoint is in the [OpenAPI document](https://api.mynth.io/openapi.json).