Webhooks

You register a URL; we POST a small JSON body to it when something happens to one of your captures. One set of endpoints covers both products — Auto Schedules and the Instant Snap API — and every delivery is signed with a secret only you and we know.

• We never send the file. The body carries ids and status, not bytes and not a download link. Fetch the capture through the API with your own key when you want it — a link in a webhook body would outlive the delivery and leak if the log were ever shared.
• Answer fast. We wait ten seconds for a 2xx. Acknowledge first and do your work afterwards.
• Expect duplicates. A delivery we are unsure about is retried, so the same id can arrive twice. Treat it as the de-duplication key.

1. 1

   Add an endpoint

   Developer Tools → Webhooks → Add endpoint. Give it a name, the Endpoint URL, and tick the events it should receive. You can limit it to one product (Auto Schedules only, Instant Snap only, or Both products), or to a single schedule.
2. 2

   Copy the signing secret

   Reveal it on the same page and store it wherever your endpoint reads its configuration. One secret covers every endpoint in the workspace.
3. 3

   Switch webhooks on in the Web Profile

   For Auto Schedules, every event is sent only for schedules whose Web Profile has Trigger webhook switched on, under After the capture. An endpoint alone is not enough.
4. 4

   Send a test

   The Send test button posts a ping immediately and shows the status code your endpoint answered with. It appears in the delivery log like any other delivery.

The endpoint form lists each event by the name in brackets below; Test ping is not in the form and appears only in the delivery log. The wire name is what arrives in type and in the X-WSW-Event header.

capture.succeeded and capture.failed from an Auto Schedule carry these fields in data. capture.changed and delivery.completed start with the same fields and add their own.

An Instant Snap capture is sent exactly as a read of it through the API returns it, without the download links.

Every capture field above, and then three more. The picture of what changed is never linked from the webhook; open the capture in the app to see it.

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-WSW-Event: capture.changed

{
  "id": "7d1c0a4e-2b9f-4e61-8c3a-5f0e9d2b1a77",
  "type": "capture.changed",
  "created_at": "2026-09-27T09:00:34.118Z",
  "product": "auto_schedule",
  "data": {
    "id": "3f2a1b0c-9d8e-4756-8493-a2b1c0d9e8f7",
    "schedule_id": "5c4b3a29-1807-4f6e-95d4-c3b2a1908f7e",
    "schedule_name": "Competitor pricing",
    "url": "https://example.com/pricing",
    "status": "succeeded",
    "media_category": "image",
    "format": "png",
    "page_http_status": 200,
    "captured_at": "2026-09-27T09:00:00.000Z",
    "final_url": null,
    "media_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "page_source": null,
    "sitemap_run_id": null,
    "change_percent": 12.4,
    "compared_to_capture_id": "a81b2c3d-4e5f-4a6b-9c7d-8e9f0a1b2c3d",
    "change_image_available": true
  }
}

Sent once per run, when every page queued in it has finished — or 12 hours after its last page was due, with any page still unfinished counted as failed. A run that queued nothing is announced at once, with status failed and the reason in message — the sitemap could not be read, no page matched, the previous run was still capturing, the plan did not allow it, or there was no active subscription. The reason is also shown in the schedule’s Sitemap runs panel. A missed run, one whose time passed unrun, sends no event.

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-WSW-Event: sitemap_run.completed

{
  "id": "c2e8f1a0-6b4d-4f3e-9a2c-1d0b8e7f6a55",
  "type": "sitemap_run.completed",
  "created_at": "2026-09-27T09:25:02.431Z",
  "product": "auto_schedule",
  "data": {
    "sitemap_run_id": "e4d3c2b1-a098-4f76-8e5d-4c3b2a190817",
    "schedule_id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
    "schedule_name": "Blog archive",
    "sitemap_url": "https://example.com/sitemap.xml",
    "status": "completed",
    "run_at": "2026-09-27T09:00:00.000Z",
    "completed_at": "2026-09-27T09:25:01.907Z",
    "pages_listed": 180,
    "pages_matched": 120,
    "pages_queued": 100,
    "pages_succeeded": 98,
    "pages_failed": 2,
    "pages_stopped": 0,
    "pages_over_limit": 20,
    "pages_over_quota": 0,
    "message": null
  }
}

Every delivery carries X-WSW-Signature in the form t=<unix seconds>,v1=<hex>. The signed text is the timestamp, a full stop, and the raw request body:

secret = whsec_testsecret
t      = 1767225600
body   = {"id":"a","type":"ping"}
signed = 1767225600.{"id":"a","type":"ping"}
v1     = c03a0b1898f8ab18939c00d5afc47d131bbd24ac9d4db23038412cfc26d58ef9

// Node.js, Express. Note express.raw: the signature is over the bytes we sent,
// so the body must not be parsed before it is checked.
import crypto from "node:crypto";

app.post("/your-endpoint", express.raw({ type: "application/json" }), (req, res) => {
    const header = req.get("X-WSW-Signature") ?? "";
    const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
    const timestamp = Number(parts.t);

    // A captured delivery is useless after a few minutes only if you check this.
    if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
        return res.status(400).send("stale");
    }

    const expected = crypto
        .createHmac("sha256", process.env.WSW_WEBHOOK_SECRET)
        .update(`${parts.t}.${req.body.toString("utf8")}`)
        .digest("hex");

    const ok =
        parts.v1?.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));

    if (!ok) return res.status(401).send("bad signature");

    // Answer first, work afterwards: we give up after 10 seconds and retry.
    res.status(200).end();
    enqueue(JSON.parse(req.body.toString("utf8")));
});

Rotating the secret takes effect immediately and invalidates nothing already sent. Accept both the old and the new secret for a few minutes while your deployment catches up.

• Any 2xx is success. A redirect is not followed and counts as a failure.
• Each delivery gets six attempts in all — immediately, then after about 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After the sixth it is marked Failed.
• After twenty consecutive failed deliveries the endpoint is switched off and we email you. Switching it back on clears the count.
• A delivery marked dropped was never sent, because the address is one we will not post to. Fix the URL rather than retrying it.

The delivery log on the Webhooks page shows every attempt for the last 30 days, with the status code and the time your endpoint took. A failed delivery can be sent again from there with Send again.

A capture request to the Instant Snap API can carry its own callback_url. It is delivered exactly like an endpoint delivery — same envelope, same headers, signed with the same workspace secret — and appears in the same log, with no endpoint name against it. It is delivered in addition to any endpoints subscribed to Instant Snap events, so a request that sets one while an endpoint also matches produces two deliveries of the same event.