Skip to main content
A webhook is a JSON POST that Stophy sends to your address when a job reports or a monitor finds something. Every call is signed, so verify the signature before you trust it. Any 2xx answer says you got it.

Events

One shape covers every source: id is the job or monitor, event says what happened, and the rest depends on the event. Your metadata, if you set it, comes last. A job sends started when it begins and page for each finished page. An agent also sends action for each step it takes. The last event is completed, failed or cancelled. These are real calls from a crawl of one page, with metadata of { "project": "docs" }. The page call is cut.
A page call holds result for a page that was read and error for one that failed. When your address falls far behind, a page call holds only the page url and resultOmitted: true. Read that page with the status call of the job. failed and cancelled have the same fields as completed, and failed also has a message. costUsd is what the job was charged so far, in dollars. creditsUsed is an older field that counts the same amount in whole steps of $0.002, rounded up. The fields of a monitor event are on Monitor webhooks.

Set a webhook

Send webhook as an address, or as an object, when you start the job. This object sets every field.
The headers you set are never kept with a delivery.

Get the signing secret

POST /v1/webhook/secret returns the secret that signs your calls. One account secret signs the calls of every job, and a monitor can have its own. Store it on your server and never in browser code or logs.
Keep the whole string, with the whsec_ prefix, as the key. Send { "rotate": true } to replace it with a new secret. The old secret stops signing at once, so deploy the new one first, or accept both for a while. Reading and rotating cost nothing.

Verify signatures

Every call has these headers. v1 is the HMAC-SHA256, in hex, of <t>.<body>, with your secret as the key. <body> is the exact text of the request body, so read it before you parse it. Compare in constant time, and reject a call whose t is more than 5 minutes from your clock.
A receiver verifies the call, stores it, and answers 200 fast. This one imports the function above from verify.ts and keeps each body once, so a call Stophy sends again changes nothing. It runs on Bun.
Serve it with Bun.serve({ port: 3000, fetch: handle }). Answer before you do slow work: a call that takes more than 5 seconds counts as failed. A retry and a replay send the same bytes, so the hash of the body is the same.

Acknowledge and retry

Your address must answer 2xx within 5 seconds. Redirects are not followed. A call that fails is tried again after 0.5, 2 and 8 seconds, so 4 attempts in all. The calls of one job or monitor are sent in order, one at a time. After 3 deliveries in a row fail, the ones still waiting are skipped.

Delivery history and retry

Every call is recorded as a delivery for 30 days, and these reads and the retry are free. The list answers with data.deliveries. Each has its id (whd_ and a uuid), sourceType, sourceId, event, url, status, how many attempts it took, and the time and status code of the last one. Monitor webhooks shows a real list. Read one delivery to see exactly what was sent. This real delivery is a monitor’s first check, to an address that answered 405.
payload is the exact JSON text that was sent. It is kept for 7 days, and not at all for a zero data retention job or after a batch’s results are deleted. The tries of a delivery show how your address answered. This real delivery got 405 four times, at 0, 0.5, 2 and 8 seconds.
ms is how long the try took. status is the code your address answered with, and error says why when it could not be reached. trigger is auto, or manual for a retry. A retry sends the same payload once, to the current address and headers of the job or monitor, signed with its current secret. It works for 7 days while the payload is kept. A try that fails is not an error. Read attempt in the answer.

Limits and errors

  • A delivery id that is not yours, or that is older than 30 days, returns 404 notFound.
  • A retry returns 400 invalidRequest when the payload was not kept, when the delivery is older than 7 days, when the monitor was deleted, or when the monitor has no webhook now.
  • A webhook.url that is not a public website address returns 400 invalidRequest.
  • webhook.events with a name the source does not send returns 400 invalidRequest. An extract takes only completed and failed.
  • Without an API key, every call here returns 401 apiKeyRequired.

Price

Free. Calls Stophy sends, the secret, the delivery reads and the retry cost nothing. The job or the monitor behind a call is charged as usual.