# Webhooks

6 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `webhooks.list`

```http
GET /web-hooks
```

Every registration (header values masked as `"********"`).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fweb-hooks).

**Response:** [`WebHookRegistration`](https://docs.maitento.com/reference/types/web-hook-registration.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/web-hooks" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const hooks = await mt.webhooks.list();
```
```python title="Python"
mt.webhooks.list()
```

## `webhooks.create`

```http
POST /web-hooks
```

Registers a URL for one entity type (one registration per URL and type).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fweb-hooks).

**Request body:** [`WebHookRegistrationCreateRequest`](https://docs.maitento.com/reference/types/web-hook-registration-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | [`WebHookType`](https://docs.maitento.com/reference/types/web-hook-type.md) | yes | What the web hook reports on. |
| `url` | `string` | yes | The URL to call. |
| `secret` | `string` | yes | A secret of your choosing that every call is signed with (`X-MT-WebHook-Signature`, an HMAC-SHA256 of `X-MT-WebHook-Timestamp` and the body), so your endpoint can check the call came from Maitento. It's never sent itself. Write-only. |
| `headers` | `map<string, string>` | yes | Extra HTTP headers to send with every call (`{}` for none). Values are write-only. |

**Response:** [`WebHookRegistration`](https://docs.maitento.com/reference/types/web-hook-registration.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/web-hooks" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"type":"AppProcess","url":"...","secret":"...","headers":{}}'
```
```ts title="TypeScript"
await mt.webhooks.create({ type: "InteractionProcess", url: "https://example.com/maitento/webhook", secret: process.env.WEBHOOK_SECRET! });
```
```python title="Python"
mt.webhooks.create(type="InteractionProcess", url="https://example.com/maitento/webhook", secret=os.environ["WEBHOOK_SECRET"])
```

## `webhooks.delete`

```http
DELETE /web-hooks/by-id/{id}
```

Deletes a registration.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fweb-hooks%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.webhooks.delete("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d");
```
```python title="Python"
mt.webhooks.delete("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d")
```

## `webhooks.get`

```http
GET /web-hooks/by-id/{id}
```

The registration with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fweb-hooks%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`WebHookRegistration`](https://docs.maitento.com/reference/types/web-hook-registration.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const hook = await mt.webhooks.get("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d");
```
```python title="Python"
mt.webhooks.get("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d")
```

## `webhooks.update`

```http
PUT /web-hooks/by-id/{id}
```

Changes the URL, secret or headers. `headers` is the full set: a missing name is removed, `null` or `"********"` keeps a stored value. Moving the URL to another origin needs the secret again. `signedOnly: true` stops a web hook registered before deliveries were signed from sending its secret in `X-MT-WebHook-Secret`: from then on its deliveries are only signed. It can't be undone, so set it once your receiver checks `X-MT-WebHook-Signature`. `false` or leaving it out changes nothing.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fweb-hooks%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`WebHookRegistrationUpdateRequest`](https://docs.maitento.com/reference/types/web-hook-registration-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | `string` | yes | The URL to call. |
| `secret` | `string \| null` |  | A new secret to sign calls with (`X-MT-WebHook-Signature`). Null or omitted: the stored secret is kept. |
| `headers` | `map<string, string \| null> \| null` |  | The complete set of headers the web hook has after the update: a name left out is removed, and `{}` clears them all. Values are write-only (responses show `********`), so a value of `null` or `********` keeps the stored value for that name; any other string replaces it. Omitting `headers` (or sending `null`) leaves every header unchanged. |
| `signedOnly` | `boolean \| null` |  | True stops a web hook registered before deliveries were signed from sending its secret in `X-MT-WebHook-Secret`: from then on its deliveries are only signed, like every web hook registered now. It can't be undone, so false or omitted changes nothing. |

**Response:** [`WebHookRegistration`](https://docs.maitento.com/reference/types/web-hook-registration.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"url":"..."}'
```
```ts title="TypeScript"
await mt.webhooks.update("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", { url: "https://example.com/maitento/webhook-v2" });
```
```python title="Python"
mt.webhooks.update("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", url="https://example.com/maitento/webhook-v2")
```

## `webhooks.deliveries`

```http
GET /web-hooks/by-id/{id}/deliveries
```

The registration's delivery log (sent deliveries are kept a day, permanent failures a week).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fweb-hooks%2Fby-id%2F%7Bid%7D%2Fdeliveries).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | `integer` |  |  |

**Response:** [`WebHookDelivery`](https://docs.maitento.com/reference/types/web-hook-delivery.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/web-hooks/by-id/<id>/deliveries" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const deliveries = await mt.webhooks.deliveries("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", { limit: 50 });
```
```python title="Python"
mt.webhooks.deliveries("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", limit=20)
```