# Webhooks

> Slicer API webhook endpoints — add an endpoint and get its signing secret, update, delete, send a test event and view the delivery log.

Source: https://docs.slicer.media/en/api/reference/webhooks/

Webhooks notify your server about events: an upload is ready, a montage or export has finished, a video was published. Requires the `webhooks` scope. The event format, the signature and how to verify it — in the guide [Webhooks](https://docs.slicer.media/en/api/webhooks/).

## Add a webhook

`POST /v1/webhooks`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Request body `CreateWebhookRequest`

| Field | Type | Description |
| --- | --- | --- |
| `url` _(required)_ | `string (uri)` | — ≤ 2048 |
| `events` _(required)_ | `string[]` |     |
| `description` | `string` | — ≤ 200 |

### Request

**curl**

```bash
curl -X POST "https://api.slicer.media/v1/webhooks" \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["upload.ready"]}'
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/hook",
    "events": [
      "upload.ready"
    ]
  }),
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.slicer.media/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
    json={
        "url": "https://example.com/hook",
        "events": ["upload.ready"],
    },
)
body = response.json()
```

### Response

**Response fields: `CreatedWebhook` (2)**

| Field | Type | Description |
| --- | --- | --- |
| `webhook` _(required)_ | `Webhook` |     |
| `secret` _(required)_ | `string` | Signing secret `whsec_…` — shown once |

Response example:

```json
{
  "ok": true,
  "data": {
    "webhook": {
      "id": "6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
      "url": "https://example.com/hook",
      "events": [
        "upload.ready"
      ],
      "description": "string",
      "enabled": true,
      "disabledReason": "string",
      "failures": 1,
      "lastDeliveryAt": "2026-10-16T09:30:00Z",
      "createdAt": "2026-10-16T09:30:00Z"
    },
    "secret": "whsec_…"
  }
}
```

## List webhooks

`GET /v1/webhooks`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Request

**curl**

```bash
curl "https://api.slicer.media/v1/webhooks" \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks', {
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
  },
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.slicer.media/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
)
body = response.json()
```

### Response

Response example:

```json
{
  "ok": true,
  "data": [
    {
      "id": "6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
      "url": "https://example.com/hook",
      "events": [
        "upload.ready"
      ],
      "description": "string",
      "enabled": true,
      "disabledReason": "string",
      "failures": 1,
      "lastDeliveryAt": "2026-10-16T09:30:00Z",
      "createdAt": "2026-10-16T09:30:00Z"
    }
  ]
}
```

## Webhook

`GET /v1/webhooks/{id}`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |

### Request

**curl**

```bash
curl "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20" \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20', {
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
  },
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
)
body = response.json()
```

### Response

**Response fields: `Webhook` (9)**

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |
| `url` _(required)_ | `string (uri)` |     |
| `events` _(required)_ | `string[]` |     |
| `description` _(required)_ | `string \| null` |     |
| `enabled` _(required)_ | `boolean` |     |
| `disabledReason` _(required)_ | `string \| null` |     |
| `failures` _(required)_ | `integer` | Failed deliveries in a row |
| `lastDeliveryAt` _(required)_ | `string \| null` |     |
| `createdAt` _(required)_ | `string` | ISO 8601 date-time, UTC |

Response example:

```json
{
  "ok": true,
  "data": {
    "id": "6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    "url": "https://example.com/hook",
    "events": [
      "upload.ready"
    ],
    "description": "string",
    "enabled": true,
    "disabledReason": "string",
    "failures": 1,
    "lastDeliveryAt": "2026-10-16T09:30:00Z",
    "createdAt": "2026-10-16T09:30:00Z"
  }
}
```

## Change a webhook

`PATCH /v1/webhooks/{id}`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |

### Request body `UpdateWebhookRequest`

| Field | Type | Description |
| --- | --- | --- |
| `url` | `string (uri)` | — ≤ 2048 |
| `events` | `string[]` |     |
| `description` | `string \| null` | — ≤ 200 |
| `enabled` | `boolean` |     |

### Request

**curl**

```bash
curl -X PATCH "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20" \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["upload.ready"]}'
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/hook",
    "events": [
      "upload.ready"
    ]
  }),
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.patch(
    "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
    json={
        "url": "https://example.com/hook",
        "events": ["upload.ready"],
    },
)
body = response.json()
```

### Response

**Response fields: `Webhook` (9)**

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |
| `url` _(required)_ | `string (uri)` |     |
| `events` _(required)_ | `string[]` |     |
| `description` _(required)_ | `string \| null` |     |
| `enabled` _(required)_ | `boolean` |     |
| `disabledReason` _(required)_ | `string \| null` |     |
| `failures` _(required)_ | `integer` | Failed deliveries in a row |
| `lastDeliveryAt` _(required)_ | `string \| null` |     |
| `createdAt` _(required)_ | `string` | ISO 8601 date-time, UTC |

Response example:

```json
{
  "ok": true,
  "data": {
    "id": "6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    "url": "https://example.com/hook",
    "events": [
      "upload.ready"
    ],
    "description": "string",
    "enabled": true,
    "disabledReason": "string",
    "failures": 1,
    "lastDeliveryAt": "2026-10-16T09:30:00Z",
    "createdAt": "2026-10-16T09:30:00Z"
  }
}
```

## Delete a webhook

`DELETE /v1/webhooks/{id}`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |

### Request

**curl**

```bash
curl -X DELETE "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20" \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
  },
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
)
body = response.json()
```

### Response

**Response fields: `object` (2)**

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |
| `deleted` _(required)_ | `boolean` |     |

Response example:

```json
{
  "ok": true,
  "data": {
    "id": "6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20",
    "deleted": true
  }
}
```

## Send a test \`ping\` event

`POST /v1/webhooks/{id}/test`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |

### Request

**curl**

```bash
curl -X POST "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/test" \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
  },
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/test",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
)
body = response.json()
```

### Response

**Response fields: `WebhookDelivery` (9)**

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `integer` |     |
| `eventId` _(required)_ | `string` |     |
| `type` _(required)_ | `string` |     |
| `status` _(required)_ | `string` | — `pending` · `succeeded` · `failed` |
| `attempts` _(required)_ | `integer` |     |
| `responseStatus` _(required)_ | `integer \| null` |     |
| `error` _(required)_ | `string \| null` |     |
| `createdAt` _(required)_ | `string` | ISO 8601 date-time, UTC |
| `deliveredAt` _(required)_ | `string \| null` |     |

Response example:

```json
{
  "ok": true,
  "data": {
    "id": 42,
    "eventId": "string",
    "type": "string",
    "status": "pending",
    "attempts": 1,
    "responseStatus": 1,
    "error": "string",
    "createdAt": "2026-10-16T09:30:00Z",
    "deliveredAt": "2026-10-16T09:30:00Z"
  }
}
```

## Last 100 deliveries

`GET /v1/webhooks/{id}/deliveries`

- **Scopes:** `webhooks`
- **Rate limit:** default

### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |

### Request

**curl**

```bash
curl "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/deliveries" \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

**JavaScript**

```js
const response = await fetch('https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/deliveries', {
  headers: {
    Authorization: `Bearer ${process.env.SLICER_TOKEN}`,
  },
});
const { ok, data, error } = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.slicer.media/v1/webhooks/6f1c2a4e-8b3d-4c1a-9e2f-3b5d7a9c1e20/deliveries",
    headers={"Authorization": f"Bearer {os.environ['SLICER_TOKEN']}"},
)
body = response.json()
```

### Response

Response example:

```json
{
  "ok": true,
  "data": [
    {
      "id": 42,
      "eventId": "string",
      "type": "string",
      "status": "pending",
      "attempts": 1,
      "responseStatus": 1,
      "error": "string",
      "createdAt": "2026-10-16T09:30:00Z",
      "deliveredAt": "2026-10-16T09:30:00Z"
    }
  ]
}
```

## Schemas

`Webhook`

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `string (uuid)` |     |
| `url` _(required)_ | `string (uri)` |     |
| `events` _(required)_ | `string[]` |     |
| `description` _(required)_ | `string \| null` |     |
| `enabled` _(required)_ | `boolean` |     |
| `disabledReason` _(required)_ | `string \| null` |     |
| `failures` _(required)_ | `integer` | Failed deliveries in a row |
| `lastDeliveryAt` _(required)_ | `string \| null` |     |
| `createdAt` _(required)_ | `string` | ISO 8601 date-time, UTC |

`CreatedWebhook`

| Field | Type | Description |
| --- | --- | --- |
| `webhook` _(required)_ | `Webhook` |     |
| `secret` _(required)_ | `string` | Signing secret `whsec_…` — shown once |

`WebhookDelivery`

| Field | Type | Description |
| --- | --- | --- |
| `id` _(required)_ | `integer` |     |
| `eventId` _(required)_ | `string` |     |
| `type` _(required)_ | `string` |     |
| `status` _(required)_ | `string` | — `pending` · `succeeded` · `failed` |
| `attempts` _(required)_ | `integer` |     |
| `responseStatus` _(required)_ | `integer \| null` |     |
| `error` _(required)_ | `string \| null` |     |
| `createdAt` _(required)_ | `string` | ISO 8601 date-time, UTC |
| `deliveredAt` _(required)_ | `string \| null` |     |