Guides
Webhooks
A watcher's webhook goes under notify:
"notify": {
"channels": ["webhook"],
"repeat": "on_change",
"cooldown": "6h",
"webhook": { "url": "https://you.example/snag", "events": ["matched", "changed", "blocked", "failing", "recovered", "ended"] }
}Events
| Event | When | data |
|---|---|---|
matched | The conditions hold for the first time | group, results, conditions, seen_at; then when a follow-up was made; added and removed for list conditions; judged for judged conditions |
changed | A matched result changed, like a new price, a new item or a size coming back | group, current (the results now), previous (the results last sent), what (the fields that changed), seen_at; added, removed and judged as for matched |
field_found | A release date, price or opening time appeared on a page | site, url, field, value |
blocked | A site blocked the check, couldn't be reached or was gone for 3 checks in a row | site, since, runs, recovered (always false), reason (blocked, unreachable or not_found) and detail |
failing | A site couldn't be read for 3 checks in a row. A robots.txt refusal (robots_disallowed) or a used-up daily cap (usage_limit) sends it on the first check | site, since, runs, reason and detail |
recovered | A site that sent blocked or failing can be read again | site, since, runs, was (blocked or failing) |
ended | The watcher stopped at its until, or at the end of a test key's day | reason (until_reached or test_key_lifetime), at |
webhook_paused | The watcher's webhook paused after 20 deliveries in a row were given up | failures, last_error, url |
clamped | The schedule was slowed to a site's minimum | clamps, each with field, asked, used, site and reason |
If you subscribe to blocked or failing, you also get recovered, so you hear when the site comes back.
When until is after_first_match or aggregate is first, the match is the last event, and no ended follows it.
A failing event means we can't check the site until something changes. Its reason is the check issue that explains it best, or failed if none does. The common ones are:
reason | What to do |
|---|---|
robots_disallowed | The site's robots.txt doesn't allow us. Watch the product on another site |
usage_limit | Your account used up its daily cap. Checks start again at midnight UTC |
recipe_broken | The page changed, and we're learning to read it again |
private_address | The URL points at a private network. Use a public URL |
Every event has the same envelope, like this changed event:
{
"id": "evt_4m2k9q8x7c1v0b3n5z6w",
"type": "changed",
"created_at": "2026-11-05T08:00:12.004Z",
"watcher_id": "wch_dhjqcvaqnhrchsnv7gtc",
"kind": "availability",
"data": {
"group": "site:allbirds.com",
"previous": [{ "site": "allbirds.com", "url": "https://www.allbirds.com/products/mens-wool-runners", "attributes": { "size": 10 }, "price": { "cents": 11000, "currency": "USD" }, "availability": "low_stock" }],
"current": [{ "site": "allbirds.com", "url": "https://www.allbirds.com/products/mens-wool-runners", "attributes": { "size": 10 }, "price": { "cents": 8800, "currency": "USD" }, "availability": "in_stock" }],
"what": ["price", "availability"],
"seen_at": "2026-11-05T08:00:11.873Z"
}
}Each result in results, current and previous has these fields:
| Field | |
|---|---|
url | The product page, post or listing to open |
site | The where.sites entry it came from |
kind | product, listing, slot, post and so on |
title | The product or listing name |
price | cents and currency, plus amount when the site gives more precision than cents |
availability | in_stock, low_stock, out_of_stock, open_slot and so on |
attributes | The variant: size, color, and the option names the store uses |
quantity, seller, date, version, release_status, release_date | When the page shows them |
image | The main photo's https URL, on sites that show one. The photo itself is never downloaded or stored |
A field the page didn't show is null, except image, which is left out. seen_at is when the results were read. In conditions, each result has site, url and held, which holds one value per condition (true, false or "unknown") in the order you wrote them.
Check seen_at before you act on a price, because after retries it can be hours older than the delivery.
Repeat and cooldown
repeat | Sends |
|---|---|
once | The first match only |
on_change | The first match, then each change (a price has to move 1% or more). The default |
every_match | Every check that matches |
cooldown is the shortest gap between two sends about the same match, 6h by default. Restocks and newly open slots ignore it, since they're often gone within the hour, and so do list and judged changes, which are each true on a single check.
confirm (2 to 5) makes a match hold for that many checks in a row before it's sent, so one odd read doesn't set it off.
False matches says when to use it.
Slack, Discord and email
We only send webhooks, so for alerts in Slack, Discord or email, point the webhook at a small function that posts them there.
Verify the signature
Every delivery has these headers:
Snag-Signature: t=1793820000,v1=5f1c0e...
Snag-Event-Id: evt_4m2k9q8x7c1v0b3n5z6wv1 is an HMAC-SHA256, in lowercase hex, of t, a period and the raw request body. The key is the whole secret, whsec_ prefix included. Use the raw bytes from before your framework parses the JSON, because parsing and re-encoding can change them. Reject any t more than 300 seconds from your clock, and compare signatures in constant time.
The secret is the webhook_secret you got when you created the watcher. The same event can arrive more than once, so skip repeats by Snag-Event-Id.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifySnag(secret, rawBody, header) {
const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac('sha256', secret).update(<span class="hljs-subst">${t}</span>.<span class="hljs-subst">${rawBody}</span>).digest('hex');
return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
import hmac, hashlib, time
def verify_snag(secret: str, raw_body: bytes, header: str) -> bool:
parts = dict(part.split("=", 1) for part 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["v1"])
Test sends and resends
Send a test webhook posts a signed test event right away and tells you what your endpoint answered. Resend an event sends a past event again with the same id. Both are also on the watcher's page in the dashboard, which shows whether each event went through.
Retries
Answer with a 2xx within 10 seconds. Any other answer, or none in time, is retried after:
- 1 minute
- 5 minutes
- 30 minutes
- 2 hours
- 12 hours
After the last try, the delivery is given up. The event stays in list events, and resend an event sends it again.
The URL has to use https and can't resolve to a private address. To test on your own machine, use a tunnel (local webhooks).
Paused webhooks
If 20 deliveries in a row are given up, the webhook pauses. New events are still recorded but aren't sent to it. A webhook_paused event with failures, last_error and url is recorded too, but never sent to the webhook that paused.
It shows in list events and on the watcher's page.
When your endpoint works again, resume the webhook:
curl -X POST https://api.watcher.manwhas.shop/v1/watchers/$WATCHER_ID/webhook/resume \
-H "Authorization: Bearer $SNAG_KEY" \
-H "content-type: application/json" \
-d '{ "redeliver": true }'It answers with { "watcher_id": "wch_…", "was_paused": true, "paused": false, "redelivered": 4 }.
With redeliver: true, the newest 100 events skipped during the pause are sent. Without it, only new events go out. Setting a new notify.webhook.url also resumes it.
So does a test send that goes through.