> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamonster.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get the result POSTed to you when a run finishes, signed so you can trust it, instead of polling.

Mediamonster can POST the result to you when a run finishes, whether it completed or failed. You don't need to poll `poll_url`. There are two ways to ask:

* **Webhook endpoints.** Add an address once, and it hears about every run on your account: from the Workbench, from a recipe, from an automation, and through the API. Each endpoint has its own signing secret, which you can rotate.
* **`webhook_url` on a call.** Pass it when you start one run, and only that run is sent there.

You can use both. A run started with `webhook_url` goes to that URL and to every endpoint that hears the event.

## Webhook endpoints

Manage endpoints under **API & MCP keys → Webhook endpoints**, or with the API. An account holds up to 10.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/webhook-endpoints \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/mediamonster",
    "events": ["run.completed", "run.failed"],
    "description": "Production"
  }'
```

| Field | What it is |
| - | - |
| `url` | An https URL on a public host, not a Mediamonster one. Credentials in the user part (`user:pass@`) are refused: [check the signature](#check-the-signature) instead |
| `events` | The events it hears. Leave it out, or send `[]`, for every event |
| `description` | A note for you, up to 200 characters |
| `enabled` | `false` to add it switched off |

The answer is the endpoint, plus `secret`: its `whsec_` signing secret. **This is the only time the secret is shown.** Copy it now. If you lose it, rotate it. A retry with the same [`Idempotency-Key`](https://docs.mediamonster.app/api/overview#idempotency) answers with the same endpoint and `"secret": null`.

| Endpoint | What it does |
| - | - |
| `GET /api/v1/webhook-endpoints` | Your endpoints, oldest first |
| `POST /api/v1/webhook-endpoints` | Add one. Answers `201` with `secret` |
| `GET /api/v1/webhook-endpoints/{id}` | One endpoint |
| `POST /api/v1/webhook-endpoints/{id}` | Change `url`, `events`, `description` or `enabled`. Send only the fields that change |
| `DELETE /api/v1/webhook-endpoints/{id}` | Delete it, and its delivery log |
| `POST /api/v1/webhook-endpoints/{id}/rotate` | A new secret. See [Rotate a secret](#rotate-a-secret) |
| `POST /api/v1/webhook-endpoints/{id}/ping` | Send it a `ping`. See [Test an endpoint](#test-an-endpoint) |
| `GET /api/v1/webhook-deliveries` | The delivery log. See [Delivery log](#delivery-log) |
| `POST /api/v1/webhook-deliveries/{id}/replay` | Send a logged delivery again |

An endpoint never shows its secret after it is made. It shows `enabled`, `disabled_reason` when we switched it off, `failing_since` while its deliveries are failing, and `previous_secret_expires_at` while a rotated-out secret still signs.

Every change to an endpoint, and every test and replay, is on your [account activity](https://docs.mediamonster.app/account/settings.md#activity).

Managing endpoints takes a key with the `admin` [scope](https://docs.mediamonster.app/api/authentication.md#scopes). A [test key](https://docs.mediamonster.app/api/authentication.md#test-mode) can list endpoints and read the delivery log, and is refused (`403 test_mode_unsupported`) on everything that adds, changes, deletes, rotates, pings or replays — those reach your real receivers. Test runs are still delivered to your endpoints, marked `"livemode": false`.

## Pass `webhook_url` on a call

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/run/clips \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/episode-12.mp4",
    "options": {"count": "8"},
    "wait": false,
    "webhook_url": "https://hooks.example.com/mediamonster"
  }'
```

It works on `POST /api/v1/run/{skill}`, `POST /api/v1/runs` and `POST /api/v1/convert`. A `webhook_url` isn't an endpoint: it has no settings, and it is signed with your account's **webhook signing secret**, shown under **API & MCP keys → Webhook signing secret**. That secret can't be rotated. Use an endpoint if you need to.

## What arrives

One POST per run, with a JSON body:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "job.completed",
  "id": "70af9b11-3126-470c-82a5-1842c58d1657",
  "created": "2026-09-23T05:00:50.250Z",
  "livemode": true,
  "data": { "…": "the same object GET poll_url returns" }
}
```

`livemode` is `false` for a run made with a [test key](https://docs.mediamonster.app/api/authentication.md#test-mode). Test runs are delivered like any other, so you can build the receiving end without spending anything.

| `type` | Sent when |
| - | - |
| `job.completed` | A single skill run or a conversion finished |
| `job.failed` | A single skill run or a conversion failed. A skill's credits have already gone back |
| `run.completed` | A recipe run finished |
| `run.failed` | A recipe run failed |
| `ping` | You asked for a test. Only sent to the endpoint you tested, and never subscribed to |

A recipe run sends one `run.*` event. Its steps don't send `job.*` events of their own.

`data` holds signed download links, and they expire. Fetch the files when the webhook arrives, or read `poll_url` again later for fresh links.

### Slack, Discord and Google Chat

A Slack, Discord or Google Chat incoming-webhook URL (`https://hooks.slack.com/services/…`, `https://discord.com/api/webhooks/…`, `https://chat.googleapis.com/v1/spaces/…/messages?key=…`) is sent a chat message instead of the JSON above: whether the run finished or failed and why, a link to each file it made (good for 7 days), the first picture, and the automation's page for a run an automation started. A test posts a test message. The delivery log still shows the JSON event.

## Check the signature

Every POST carries a header:

```
Mediamonster-Signature: t=1790000000,v1=5257a869e7…
```

`v1` is HMAC-SHA256 of `t`, a full stop, and the raw request body, keyed with the signing secret: the endpoint's own, or your account's for a `webhook_url`. Both start `whsec_`.

While a rotation overlaps, the header carries **two** `v1` values, one for each secret, newest first:

```
Mediamonster-Signature: t=1790000000,v1=9f86d081…,v1=5257a869e7…
```

To check a request:

1. Take the raw body exactly as it arrived. Do this before any JSON parsing.
2. Compute `HMAC-SHA256(secret, t + "." + body)` in hex.
3. Compare it to **every** `v1` in the header with a constant-time comparison. Accept the request if any one matches.
4. Refuse anything whose `t` is more than five minutes from now. This stops a captured request from being replayed later.

```js Node theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import crypto from "node:crypto";

function verify(secret, header, rawBody) {
  let t = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=");
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(value);
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"),
  );
  return signatures.some((sig) => {
    const given = Buffer.from(sig);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import hashlib
import hmac
import time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    t = None
    signatures = []
    for part in header.split(","):
        key, _, value = part.partition("=")
        if key == "t":
            t = int(value)
        elif key == "v1":
            signatures.append(value)
    if t is None or abs(time.time() - t) > 300:
        return False
    expected = hmac.new(
        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in signatures)
```

The scheme is the same one Stripe uses, so a Stripe verification helper works if you change the header name.

## Rotate a secret

Rotating gives an endpoint a new secret. The old one keeps signing beside it for an overlap, so you can deploy the new secret without refusing what arrives meanwhile.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/webhook-endpoints/{id}/rotate \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours": 24}'
```

* `overlap_hours` is 24 if you leave it out, and can be anything from 0 to 168 (a week). `0` retires the old secret at once.
* The answer carries the new `secret`, once.
* Until `previous_secret_expires_at`, every delivery carries two `v1` signatures. A receiver holding either secret accepts it.
* Rotating again during an overlap retires the oldest secret. Only two ever sign.

In the app, press **Rotate secret** on the endpoint and pick how long to keep the old one.

## Test an endpoint

**Send test** in the app, or `POST /api/v1/webhook-endpoints/{id}/ping`, sends the endpoint a `ping`:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "type": "ping",
  "id": "d9428888-122b-4c1a-a4b6-2f2e6d5b0e1f",
  "created": "2026-09-26T10:00:00.000Z",
  "data": {
    "endpoint_id": "…",
    "message": "A test from Mediamonster. Answer with any 2xx and this endpoint is working."
  }
}
```

It is signed like any other delivery, so it tests your signature check too. It is sent even to an endpoint that is switched off, so you can test one before you switch it on. The answer is the ping's `event_id`. Look it up in the delivery log a moment later.

## Delivery log

Every attempt to send an event is logged for 30 days, retries included, each as its own row. In the app it's under **Deliveries** below your endpoints: open a row to see what was sent and what came back.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl "https://mediamonster.app/api/v1/webhook-deliveries?status=failed&endpoint_id={id}" \
  -H "Authorization: Bearer mm_live_…"
```

| Parameter | What it does |
| - | - |
| `endpoint_id` | Only this endpoint's deliveries |
| `status` | `pending`, `succeeded` or `failed` |
| `limit` | Rows a page, up to 100. 25 if you leave it out |
| `cursor` | The `next` from the page before |

Returns `{"deliveries": [...], "next": "…"}`, newest first. `next` is `null` on the last page. Each delivery has:

| Field | What it is |
| - | - |
| `id` | The delivery |
| `endpoint_id` | The endpoint, or `null` for a call's `webhook_url` |
| `event_id`, `event_type` | The body's `id` and `type`. Every attempt at one event shares its `event_id` |
| `url` | Where it was sent |
| `attempt` | 1 for the first try, then 2, 3… for each retry |
| `status` | `pending` while it's being sent, then `succeeded` or `failed` |
| `response_status` | The HTTP status your receiver answered with, or `null` if it never answered |
| `response_body` | The first 2 KB of what it answered |
| `duration_ms` | How long the attempt took |
| `error` | Why it failed, when there's no answer to show: a timeout, a refused connection, a redirect |
| `request_body` | The body that was sent |
| `replay_of` | The delivery this one replayed, if it is a replay |
| `created_at` | When the attempt started |

### Replay a delivery

**Replay** on a logged delivery, or `POST /api/v1/webhook-deliveries/{id}/replay`, sends the same body again to the same address. It keeps the same `id`, so your de-duplication still works, and it is signed with the secrets that are live now. It is sent even to an endpoint that is switched off. The new attempt is logged with `replay_of` set.

## Delivery

* **Answer with any 2xx** within 15 seconds. Anything else counts as a failed attempt, and so does a redirect. The attempt is retried with growing gaps, up to eight times. Each address is retried on its own, so one that's down never holds up the others.
* **Sent once per run, per address.** A retry can arrive after a slow success you've already handled, and so can a replay, so key your handling on `id`.
* **https only**, never a private address and never a Mediamonster one. A `webhook_url` that isn't accepted is refused with `bad_webhook` before anything is charged.
* To know a delivery is ours, [check its signature](#check-the-signature) — don't rely on a secret in the URL. Credentials in the user part of the URL (`user:pass@`) are refused, and your account activity shows an endpoint's address without its query string.

### Endpoints that keep failing

An endpoint that has failed 20 attempts in a row, over at least three days, is switched off. Its `disabled_reason` says why, and your account activity shows when. A short outage never trips this, however many retries it causes. Fix the receiver, then switch the endpoint back on: that clears the reason and starts the count again. Replay anything you missed from the delivery log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.