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.
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
Sendwebhook 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.
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.
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.
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 answer2xx 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 invalidRequestwhen 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.urlthat is not a public website address returns400 invalidRequest. webhook.eventswith a name the source does not send returns400 invalidRequest. An extract takes onlycompletedandfailed.- 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.Related
- Monitor webhooks lists the monitor events.
- Read a crawl polls a crawl instead of waiting for a call.
- Rate limits covers the limits on these calls.
- Website change digest builds a receiver end to end.