Best Practices

Guidelines for building reliable integrations with DiffHook — retries, idempotency, signature verification, rate-limit awareness, and webhook handler design that survives production traffic.

Use CSS selectors to reduce noise

Pages change constantly — cookie banners update, ads refresh, timestamps tick. Scope your monitors to the content you actually care about:

{
  "css_selector": "#pricing-table"
}

This reduces false positives and makes your diffs more meaningful.

Use JS rendering only when needed

Headless browser rendering is slower and more resource-intensive. Only enable it when the target page genuinely requires JavaScript to render meaningful content.

Most news feeds, documentation sites, and pricing pages are server-rendered and don't need it.

Respond to webhooks quickly

Your endpoint should return 200 OK within 10 seconds. Timeouts and non-2xx responses trigger automatic retries with exponential backoff in minutes (see Receiving Webhooks).

Process payloads asynchronously — push to a queue, save to a database, then return 200 immediately.

Idempotency

Webhooks can be delivered more than once in rare failure scenarios. Use the monitor_id + triggered_at combination as a deduplication key:

const eventKey = `${body.monitor_id}:${body.triggered_at}`
if (await redis.get(eventKey)) return // Already processed
await redis.set(eventKey, '1', 'EX', 86400)

Choose the right interval

A good rule of thumb:

Use case	Recommended interval
Flash sales, price alerts	5–15 min
Competitor monitoring	60 min
Regulatory filings	360 min (6h)
Job boards, career pages	1440 min (daily)

Verify signatures

Always verify the X-Signature header before processing webhook payloads. This protects against spoofed requests. See the Verifying Signatures guide for implementation examples.