webhook sends a signed JSON POST to your address when it finds a change and when a check ends. This page covers what monitors send. Webhooks covers signatures, retries and delivery history for every call Stophy makes to you.
Events
Pick the events inwebhook.events.
A monitor made with
targets and schedule sends monitor.page and monitor.check.completed when you pick none. A monitor made with the older url, urls and interval fields sends monitor.changed and monitor.failed.
The first check of a monitor reads each page for the first time, so it sends no monitor.page. It does send monitor.check.completed. Subscribe to it to know that checks run, even when nothing changes.
Set a webhook
Sendwebhook when you create a monitor, or set it later with PATCH /v1/monitor/{id}. This is the object from the request on Monitors.
PATCH replaces the webhook as a whole, so send every field you want to keep. Send "webhook": null to remove it.
Read an event
Every event is a JSON object.id is the id of the monitor, event is the event name, and your metadata comes last. The call carries Stophy-Signature and User-Agent: Stophy-Webhook/1.
A page changed. This real event came from a monitor with a goal.
changeStatus is changed, new or removed. A removed page has only url, changeStatus and at. A result of a search target also has its title. With json comparison the event holds json, each field before and after. judgment is there when the monitor has a goal. A judgment with meaningful: false is still sent, so you decide what to do with it.
A check ended. This is the real event of a monitor’s first check. costUsd is what the check was charged, in dollars. actualCredits is an older field that counts the same amount in whole steps of $0.002, rounded up, so a check of $0.001 shows 1.
monitor.failed has reason and at. When one page keeps failing, it also has the url and failures, which is 5. When your balance runs out, the reason is Your balance ran out, so this monitor is paused.
An event has no id of its own. A retry or a replay sends the same body again. To ignore an event you have already handled, keep a hash of the body, or the checkId for check events and the url with at for page events.
Verify the signature
Every call has aStophy-Signature header, t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of <t>.<body> with your webhook secret, over the exact bytes of the body. Compute it, compare it in constant time, and reject a call whose t is more than a few minutes old. Webhooks has the code.
Until you rotate a monitor’s secret, its calls are signed with your account secret from POST /v1/webhook/secret. After you rotate it, they are signed with the monitor’s own secret.
Rotate the signing secret
POST /v1/monitor/{id}/webhook/rotate-secret gives one monitor’s calls a new secret. The monitor needs a webhook. The samples read the monitor’s id from MONITOR_ID.
400 invalidRequest: This monitor has no webhook, so there is no secret to replace.
Check deliveries
Each call is a delivery. Events of one monitor are sent in order, one at a time. Your address must answer2xx within 5 seconds. A call that fails is tried again after 0.5, 2 and 8 seconds, so 4 attempts in all. Redirects are not followed.
List the deliveries of a monitor with GET /v1/webhook/deliveries. This real answer lists two calls to an address that answered 405. The second was also retried by hand once, so it has 5 attempts.
POST /v1/webhook/deliveries/{id}/retry. A retry goes to the monitor’s current address and secret. See Webhooks.
Get an email instead
A monitor can email you when a check finds a change. Sendnotification when you create or update the monitor.
The monitor shows each recipient’s state in
notification.email.recipientStates: confirmed, pending or unsubscribed.
Limits and errors
webhook.urlmust be a public website address. A private or local address returns400 invalidRequest.webhook.eventsacceptsmonitor.page,monitor.check.completed,monitor.changedandmonitor.failed. Another name returns400 invalidRequestwithwebhook.events.0: Send one of: monitor.page, monitor.check.completed, monitor.changed, monitor.failed.- After 3 deliveries in a row fail, the events still waiting are skipped and show
skipped. - A delivery is kept for 30 days, and its payload for 7 days.
Price
Free. Webhooks, deliveries, retries and secrets cost nothing. A check costs what it costs, whether or not you have a webhook. See Monitors.Related
- Webhooks explains signatures, retries and delivery history.
- Checks and changes reads the same results by polling.
- Website change digest builds a daily summary from these events.