Webhooks
Get a signed POST when a recording in your workspace is ready: the payload, the signature and how to check it.
A workspace can tell other tools about every new recording. When a recording is ready (and its AI summary, when there is one), Midge sends a POST with a JSON body to each of the workspace’s webhook addresses. Recordings set to Only me aren’t sent.
Add a webhook
Workspace owners and admins open Settings › Workspace › Webhooks on midge.dev and add an https:// address. Midge shows the signing secret once; keep it with the code that receives the webhook. Send test sends a ping and shows what your server answered.
Midge only calls addresses on the public internet, doesn’t follow redirects and waits 10 seconds for an answer. Any 2xx counts as delivered. Otherwise it tries again after a minute and after five more. After 20 failures in a row it stops calling that address until you send a test.
The request
Headers:
| Header | Value |
|---|---|
Midge-Event | recording.created, or ping for a test |
Midge-Delivery | A unique id for this delivery (evt_…); a retry has the same body and id |
Midge-Signature | t=<unix seconds>,v1=<signature> |
Body:
{
"id": "evt_3f9c…",
"event": "recording.created",
"created_at": "2026-11-12T16:20:08.512Z",
"recording": {
"id": "Z0zhhKotyJGV",
"url": "https://midge.dev/r/Z0zhhKotyJGV",
"title": "Checkout fails with 500",
"kind": "video",
"client": "extension",
"description": "",
"page_url": "https://shop.example/cart",
"duration_ms": 61000,
"console_errors": 1,
"failed_requests": 1,
"created_at": "2026-11-12T16:19:41.002Z",
"created_by": { "name": "Ada" },
"workspace": { "id": "8c0e…", "name": "Acme" },
"visibility": "workspace",
"ai": {
"title": "Paying returns 500 when the cart has a coupon",
"summary": "…",
"steps": ["Open the cart", "Click Pay now"],
"likely_cause": "…"
}
}
}
ai is there only when the recording has an AI summary. A ping has "recording": null.
Check the signature
The signature is the HMAC-SHA256 of <t>.<raw body>, keyed with your secret, in hex. Compute it over the raw bytes you received, before parsing the JSON, and reject requests whose t is more than five minutes old.
import crypto from 'node:crypto';
export function isFromMidge(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
}
import hashlib, hmac, time
def is_from_midge(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split('=', 1) for p in header.split(','))
if abs(time.time() - int(parts['t'])) > 300:
return False
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get('v1', ''))