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.
- Save the
signing_secretsecurely 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. - Include
webhookin thechannelsof a watch. - 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.