Website Buddy API v1

Every POST must carry an Idempotency-Key header: a value you make for that one operation, such as a UUID. If the request times out, send it again with the same key and the same body. The first request does the work; each repeat gets its status and body back, marked Idempotent-Replayed: true with the Original-Request-Id — no second site, no second fee.

KEY=$(uuidgen)   # one key per operation; reuse it only to retry it
curl -X POST "https://websites.workflowcorp.com/api/v1/sites" \
  -H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"template_id":"TEMPLATE_ID","name":"Maple Street Bakery"}'

• Keys are 8 to 255 characters (letters, digits and - _ . : ~ + / =), belong to the API key that sent them, and are remembered for 24 hours.
• PATCH and DELETE accept a key but don’t require one: doing them twice is harmless. GET ignores it.
• One POST takes NO key: create_sign_in_link. Its answer is a one-time sign-in link, which is never saved for a replay — a key is refused with 400 idempotency_key_not_accepted. Calling it again simply makes a new link.
• Replayed as first answered: success, 404 not_foundand 409 refusals. Not kept: 422 (fix the body; the same key may be used) and 5xx (nothing was saved). A request refused before its key is read (400, 401, 403, 413, 415, 429) doesn’t use the key up.
• The write and the answer a retry will get are saved in one database transaction — both or neither.
• MCP tool calls carry the key as an idempotency_key argument, with the same rules — and the same fingerprint, so an MCP retry and a REST retry of one operation replay each other.

v1 is the hex HMAC-SHA256 of {t}.{raw body} under your webhook’s secret (whsec_…, shown once when it’s made or rolled). Compare in constant time and refuse a t more than 5 minutes old.

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

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return want.length === parts.v1?.length && timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1));
}

• Answer any 2xx within 10 seconds. Anything else — an error, a redirect, no answer — is tried again after 1 minute, 5, 30, then 2, 6 and 12 hours (7 tries in all), then marked as given up.
• Delivery is at least once: the same event can arrive twice. Keep the event id and ignore one you’ve seen.
• After 20 events in a row are given up, the webhook pauses itself; resume it in Settings → Webhooks or with update_webhook (paused=false).
• Money in a payload is integer cents. Text in a payload is what a visitor typed — treat it as data.