Skip to main content

Signed webhooks

Receive restock alerts at an HTTPS endpoint and verify signatures with Node.js or Python.

View Markdown

Set a destination

Hunt, Fleet, and Reseller accounts can set one public HTTPS destination. Use PUT /api/agent/v1/webhook or the MCP set_webhook tool with webhook_url.

  1. Save the signing_secret securely when you first set the URL, change it, or rotate the secret. If you save the same URL and receive no new secret, keep using the one you stored.
  2. Include webhook in the channels of a watch.
  3. Send {"rotate_secret":true} to rotate the current URL’s secret. Send {"webhook_url":null} to clear the destination.

The restock event

RefurbSitter sends an HTTPS POST with Content-Type: application/json for a matched restock. The payload below uses illustrative values.

{
  "content": "Mac Studio restock — A configuration matched your watch.\nhttps://www.apple.com/shop/refurbished/mac/mac-studio",
  "text": "Mac Studio restock — A configuration matched your watch.\nhttps://www.apple.com/shop/refurbished/mac/mac-studio",
  "title": "Mac Studio restock",
  "body": "A configuration matched your watch.",
  "url": "https://www.apple.com/shop/refurbished/mac/mac-studio",
  "part_number": "EXAMPLE/A",
  "type": "restock.alert",
  "schema_version": 1,
  "id": "evt_0123456789abcdef0123456789abcdef"
}

content and text contain the same summary. part_number is present when the listing provides a part number. id is the event identity and also appears in X-RefurbSitter-Event-Id. Use the ID from the signed body for deduplication.

Verify the signature

Read X-RefurbSitter-Timestamp as a Unix timestamp in seconds and X-RefurbSitter-Signature as v1= followed by a lowercase hex digest.

Compute HMAC-SHA256 over the UTF-8 timestamp string, one period, and the raw request body bytes. Use the signing secret as UTF-8 text, even though the returned secret looks like hex. Compare v1= plus the computed hex digest to the header with a constant-time comparison.

The examples use a five-minute clock tolerance. Pass the original request bytes to the function and parse the JSON only after verification succeeds.

Node.js verification

Pass a Buffer, such as Buffer.from(await request.arrayBuffer()), along with the two header values and your signing secret.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyRefurbSitter(rawBody, timestamp, signature, secret) {
  if (!/^[0-9]+$/.test(timestamp ?? "")) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature ?? "")) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;

  const digest = createHmac("sha256", secret)
    .update(timestamp + ".", "utf8")
    .update(rawBody)
    .digest("hex");

  return timingSafeEqual(Buffer.from("v1=" + digest), Buffer.from(signature));
}

Python verification

Pass the raw body as bytes, the two header values as strings, and your signing secret as a string.

import hashlib
import hmac
import re
import time


def verify_refurbsitter(raw_body, timestamp, signature, secret):
    if not re.fullmatch(r"[0-9]+", timestamp or ""):
        return False
    if not re.fullmatch(r"v1=[a-f0-9]{64}", signature or ""):
        return False
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    signed_bytes = (timestamp + ".").encode("utf-8") + raw_body
    digest = hmac.new(secret.encode("utf-8"), signed_bytes, hashlib.sha256)
    return hmac.compare_digest("v1=" + digest.hexdigest(), signature)

Delivery and retries

DNS lookup and the HTTPS request share an eight-second deadline. A 2xx response marks delivery successful. Redirects count as failures. A connection failure before TLS is established can try another resolved public address within the same deadline.

On Hunt, Fleet, and Reseller, RefurbSitter sends webhooks as soon as it detects a matching restock. If delivery fails, RefurbSitter may try again if it processes the same restock event again. Webhooks have no scheduled retries.

If the same event is sent again, it keeps its event ID. Each request is signed with its send timestamp. Verify the signature first, then record the signed id with your event processing. Return 2xx for an event you already processed.