Skip to content

Menu

Build a price monitor with webhooks

Build a one-product price monitor with Scraipe Watches, signed webhooks, exact USD comparisons, durable receipt checks and missed-event reconciliation.

By Codex. Checked 2026-11-20.

A price monitor needs more than a timer: it must keep product identity stable, distinguish a price change from missing data, and receive the change without turning repeated deliveries into repeated alerts. Use a Scraipe Watch for scheduled extraction and a receiver you control for the price policy.

This guide builds a one-product, USD price-drop pilot. Its Node.js 22 receiver records proposed alerts locally; it does not send email or create a hosted watch. The 19 downloadable tests and eight controlled Watch scenarios were checked on 20 November 2026. Product records and prices are invented teaching data.

Define the product and the alert policy

Start with one URL you are permitted to monitor. Inspect the actual product or variant identifier, current price and explicit currency on that page. A title is usually a poor identity: a title edit should not look like a removed product and a new one.

Use keyFields: ["sku"] and ensure the extracted SKU is present, unique and stable. Scraipe's diff uses those fields to pair records. Duplicate or missing identifiers can collapse records during matching; do not expect the webhook receiver to recover rows already lost upstream. Test the extraction on representative pages before scheduling it.

The example policy is deliberately narrow:

Input or changeDecision
Same configured SKU, USD, "19.00" to "17.50"Record a proposed USD 1.50 price-drop alert
Price rises, stays equal, or falls by less than USD 1.00Record no alert
Title changes but price does notRecord no price alert
Price is missing, numeric, "N/A", "17,50" or "$17.50"Hold for review
Currency changes or is missingHold for review; do not compare currencies
A row is added or removedReview product identity and extraction coverage
The watch failsRecord an operational review item, not a price change

Use exact decimal strings and integer minor units for the comparison. The receiver accepts up to nine whole-number digits followed by exactly two decimal digits and calculates the drop with BigInt. This USD-specific rule does not cover every currency or locale. See price normalization before broadening the input policy.

Run the receiver locally first

Download these eight files into one empty directory, keeping their names:

There are no npm dependencies. Run the tests; they open temporary loopback listeners and exercise authentication, price policy, duplicate handling, restart recovery, body limits and persistence failures.

bash

node --test monitor.test.mjs
export SCRAIPE_WEBHOOK_SECRET='whsec_PUBLIC_TEACHING_KEY_DO_NOT_USE_IN_PRODUCTION'
node receiver.mjs config.example.json

Leave that terminal running. In a second terminal, from the same directory:

bash

node demo.mjs
node demo.mjs

The sender only calls 127.0.0.1:8787. It signs the original fixture bytes using the current clock. The first response includes:

json

{
  "status": 200,
  "accepted": true,
  "duplicate": false,
  "outcome": {
    "decision": "price_drop",
    "sku": "SKU-1",
    "currency": "USD",
    "from": "19.00",
    "to": "17.50",
    "dropMinor": "150"
  }
}

The second response has duplicate: true. Inspect inbox.jsonl: there is one accepted event, including its original payload and decision. Restarting the receiver preserves this duplicate check. If you already ran the fixture in that directory, it remains a duplicate; use a new empty directory to repeat the first-acceptance experiment. Stop the receiver with Ctrl-C. The public teaching key above must never protect real deliveries.

Create and pause a small Watch pilot

Use an API key with watches for writes and read for inspection; use scrape as well if you validate the extraction through /v1/scrape. Keep sufficient credits for extraction work. Watches have a minimum interval of five minutes; the request template uses one hour and explicitly selects egress: "direct".

Edit watch-request.json: replace the reserved example URL, select the actual identity fields and describe the price/currency fields accurately. The template supplies an array-of-records JSON Schema. A schema is an extraction contract, not independent proof that the source price is correct. Validate the returned records against the page before accepting a baseline.

The template intentionally omits a webhook until you have the new watch's ID and secret. Creating a watch makes it active, with its first run due promptly, approximately five seconds later. An immediate pause can race that first run; it is not a guarantee that no extraction has happened or been charged.

bash

umask 077
export API='https://scraipe-fc66a552921e.herokuapp.com'
curl --fail-with-body --silent --show-error \
  "$API/v1/watches" \
  -H "Authorization: Bearer $SCRAIPE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @watch-request.json > created-watch.json

A successful response is HTTP 201 with watch, webhookSecret and estimatedCredits. Securely save the secret immediately; it is shown once. Keep the response out of source control and logs. Set WATCH_ID to watch.id, then pause while configuring the receiver:

bash

curl --fail-with-body --silent --show-error \
  -X PATCH "$API/v1/watches/$WATCH_ID" \
  -H "Authorization: Bearer $SCRAIPE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"active":false}'

Pausing prevents future scheduled runs; it does not cancel a run already in progress. Read the watch detail and run history to establish what actually happened. Retain the watch ID and request, and inspect the snapshot after a successful baseline.

Connect the signed delivery to your receiver

The local example binds only to loopback. A hosted Scraipe Watch cannot deliver to your laptop's 127.0.0.1. For a real pilot, put an HTTPS ingress you control in front of the receiver, preserve the raw request body, provision persistent storage and use the actual secret through your secret manager. Pin config.watchId to the new ID, sku to the expected product and currency to USD. Keep one receiver process per journal.

While the watch is paused, PATCH its webhook to your HTTPS /hooks/scraipe endpoint. An example configuration body is:

json

{
  "active": false,
  "webhook": "https://your-app.example/hooks/scraipe",
  "notifyOn": "changes"
}

Replace the reserved hostname before sending it. Use a direct endpoint: webhook delivery follows no redirects. The signing header is X-Scraipe-Signature: t=...,v1=...; the MAC covers the timestamp, a dot and the exact request bytes. Parsing JSON and serializing it again before verification can change those bytes and invalidate the signature.

The example checks HMAC-SHA256, a five-minute past/future timestamp window, the expected watch, and matching event/delivery headers. It uses equal-length buffers with Node's timing-safe comparison. Missing, invalid or old signatures are rejected. A valid signature establishes who signed the bytes; it does not establish that extraction interpreted the source correctly.

Accepted events are appended and flushed to the local journal before HTTP 200. A price_drop is a proposed business action for a downstream worker. Review items are also acknowledged after storage so they remain inspectable. Matching watch/run events are deduplicated; conflicting content for a seen run returns 409. Journal write failure returns 503, and an incomplete journal refuses startup until inspected.

Verify baseline, price change and failure behaviour

Use POST /v1/watches/$WATCH_ID/run to run the paused pilot manually. With notifyOn: "changes", the first successful run captures the baseline and sends no change webhook. No webhook at that point is expected, but you still need to verify a successful run and its snapshot. An unchanged later run also sends none. Failures notify unless notifyOn is never.

On a controlled source you own, make one deliberate price change and run again. Confirm the source record, run.id, diff, run.delivery, receiver journal and proposed amount agree. Do not modify another party's product page or repeatedly scrape it simply to force an alert. After the pilot is checked, PATCH active: true to resume scheduling.

The following was reproduced against the actual repository Watch diffing, state and signing code. Extraction used invented records; transport went only to a local receiver. This is local integration evidence, not an authenticated hosted Watch test.

Controlled scenarioObserved result
First successful recordBaseline recorded; no delivery
USD 19.00 to 17.50Signed delivery accepted; proposed 150-cent drop
Title-only editDelivery stored; no price alert
Extracted price becomes N/AReview item
Origin refusalwatch.failed review item
Valid price after the malformed prior priceReview item because the prior value cannot be compared
Receiver deliberately returns 503 on a changeOne failed delivery recorded
Next run returns the same priceNo change event; the missed delivery is not resent

Reconcile missed events and budget the runs

Each webhook delivery is attempted once. Returning 503 does not request an automatic retry. A failed webhook does not undo the watch's successful snapshot update. The next unchanged run therefore cannot be relied on to repeat that change.

Inspect GET /v1/watches/$WATCH_ID/runs and each run's delivery outcome. Current local run history keeps at most 50 runs, and stored change lists are capped at 50 entries per category with a truncated flag. Collect and reconcile history before it rolls off. A snapshot gives the latest records, not every intermediate price. Pause the pilot if you cannot establish that its missing events were handled.

Use authenticated run-history data through a separate trusted reconciliation path keyed by watch ID and run ID. Do not replay an old unsigned body into the public webhook endpoint, invent a fresh signature or disable timestamp checking to recover it. A new manual run is a new extraction, not redelivery of an old event.

For production alerts, replace the illustrative journal with a transactional inbox/outbox and an idempotent worker. Add backups, retention, capacity controls and failure monitoring. The example loads its journal in memory and sends no external notifications; file flushing is not a guarantee against host or disk failure. Multiple processes must not share this journal, and no exactly-once external delivery is claimed.

Inspect run credits and current pricing. The first extraction can require learning, later runs can require repair or fallback, and a direct network choice does not make model work free. Keep network changes explicit; a refusal is not a reason to silently enable residential fetching. The recurring repair budget and freshness policy explain why price monitoring needs both a spend allowance and a maximum acceptable observation age.

The API reference covers manual-run failures, concurrency responses and watch inspection. Start with one permitted product in the playground, validate its extraction, and expand only after the complete pilot is observable.

Sources and verification

Try the next step

Try the playground

Continue building