Snag Watcher

Guides

Webhooks

A watcher's webhook goes under notify:

JSON
"notify": {
  "channels": ["webhook"],
  "repeat": "on_change",
  "cooldown": "6h",
  "webhook": { "url": "https://you.example/snag", "events": ["matched", "changed", "blocked", "failing", "recovered", "ended"] }
}

Events

EventWhendata
matchedThe conditions hold for the first timegroup, results, conditions, seen_at; then when a follow-up was made; added and removed for list conditions; judged for judged conditions
changedA matched result changed, like a new price, a new item or a size coming backgroup, current (the results now), previous (the results last sent), what (the fields that changed), seen_at; added, removed and judged as for matched
field_foundA release date, price or opening time appeared on a pagesite, url, field, value
blockedA site blocked the check, couldn't be reached or was gone for 3 checks in a rowsite, since, runs, recovered (always false), reason (blocked, unreachable or not_found) and detail
failingA 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 checksite, since, runs, reason and detail
recoveredA site that sent blocked or failing can be read againsite, since, runs, was (blocked or failing)
endedThe watcher stopped at its until, or at the end of a test key's dayreason (until_reached or test_key_lifetime), at
webhook_pausedThe watcher's webhook paused after 20 deliveries in a row were given upfailures, last_error, url
clampedThe schedule was slowed to a site's minimumclamps, 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:

reasonWhat to do
robots_disallowedThe site's robots.txt doesn't allow us. Watch the product on another site
usage_limitYour account used up its daily cap. Checks start again at midnight UTC
recipe_brokenThe page changed, and we're learning to read it again
private_addressThe URL points at a private network. Use a public URL

Every event has the same envelope, like this changed event:

JSON
{
  "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
urlThe product page, post or listing to open
siteThe where.sites entry it came from
kindproduct, listing, slot, post and so on
titleThe product or listing name
pricecents and currency, plus amount when the site gives more precision than cents
availabilityin_stock, low_stock, out_of_stock, open_slot and so on
attributesThe variant: size, color, and the option names the store uses
quantity, seller, date, version, release_status, release_dateWhen the page shows them
imageThe 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

repeatSends
onceThe first match only
on_changeThe first match, then each change (a price has to move 1% or more). The default
every_matchEvery 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:

Text
Snag-Signature: t=1793820000,v1=5f1c0e...
Snag-Event-Id: evt_4m2k9q8x7c1v0b3n5z6w

v1 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.

JavaScript
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)); }

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. 1 minute
  2. 5 minutes
  3. 30 minutes
  4. 2 hours
  5. 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
curl -X POST https://api.watcher.staging.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.

In the examples