{
  "what": "Signed webhooks to a listing's owner when something happens to the listing. Free. Owner only (claim token per listing). Alerts never change a listing's place, status or score.",
  "events": {
    "listing.status_changed": "status moved (verified, failing, unverified, delisted), with the reason",
    "listing.price_changed": "the live 402 now quotes a different amount",
    "listing.purchase": "we bought the listing: delivered or not, the reason, and the transaction"
  },
  "create": {
    "method": "POST",
    "url": "https://api.nohumans.directory/v1/alerts",
    "body": {
      "url": "https://your.app/hooks/nohumans",
      "listings": [
        {
          "id": "<listing id>",
          "claim_token": "<its claim token>"
        }
      ],
      "events": [
        "status",
        "price",
        "purchase"
      ]
    },
    "note": "We POST a test event to your URL first; it must answer 2xx within 5 s. Up to 100 listings per hook. The reply carries the hook id and its secret, once."
  },
  "manage": {
    "status": "GET https://api.nohumans.directory/v1/alerts/<hook id>",
    "test": "POST https://api.nohumans.directory/v1/alerts/<hook id>/test",
    "stop": "DELETE https://api.nohumans.directory/v1/alerts/<hook id>",
    "auth": "x-alert-secret: <secret>"
  },
  "verify": "x-nohumans-signature is v1=<hex HMAC-SHA256(secret, x-nohumans-timestamp + '.' + raw body)>. Reject timestamps older than a few minutes; x-nohumans-delivery is the same on every retry of one event, so dedupe on it.",
  "delivery": "HTTPS only, public addresses only, 5 s timeout, redirects not followed. Retried with backoff for about a day (6 tries); a hook failing 20 deliveries in a row is switched off (its status says why).",
  "ownership": "If a listing is claimed again after you subscribed (a new claim token), it pauses on this hook; subscribe again with the new token.",
  "registration": "The test event we send while creating the hook is signed with the secret that the reply then gives you, so it cannot be verified yet: answer any alerts.test with registration: true with 2xx. Verify every other delivery, including POST /v1/alerts/<hook id>/test (registration: false).",
  "timestamps": "x-nohumans-timestamp: Unix seconds, as a decimal string (the signed value). In bodies, every *_at field is Unix seconds (integer) with a *_iso twin in UTC (2026-11-10T09:48:28Z).",
  "examples": {
    "headers": {
      "content-type": "application/json",
      "user-agent": "nohumans-alerts/1 (+https://nohumans.directory/sellers#alerts)",
      "x-nohumans-event": "listing.purchase",
      "x-nohumans-delivery": "dlv_1042",
      "x-nohumans-timestamp": "1794304110",
      "x-nohumans-signature": "v1=<64 hex chars>"
    },
    "alerts.test": {
      "type": "alerts.test",
      "id": "evt_test_3f9a1c22b7e0",
      "created_at": 1794304108,
      "hook_id": "hk_0123456789abcdef",
      "registration": false,
      "note": "A test event, signed with your hook's secret: verify it as you would a real one.",
      "docs": "https://nohumans.directory/sellers#alerts",
      "created_at_iso": "2026-11-10T09:48:28Z"
    },
    "listing.purchase": {
      "type": "listing.purchase",
      "id": "evt_1042",
      "created_at": 1794304108,
      "listing": {
        "id": "<listing id>",
        "name": "<listing name>",
        "endpoint_url": "https://api.example.com/v1/route",
        "page": "https://nohumans.directory/l/<listing id>"
      },
      "data": {
        "delivered": false,
        "failure_reason": "rejected_400_blind_request",
        "http_status": 400,
        "tx_hash": null,
        "amount_usdc": 0,
        "attempted_at": 1794303500,
        "next": {
          "after_fixing": "POST https://api.nohumans.directory/v1/listings/<listing id>/verify-now (a paid re-check, owner only)",
          "your_numbers": "https://nohumans.directory/sellers/report?id=<listing id>"
        },
        "attempted_at_iso": "2026-11-10T09:38:20Z"
      },
      "created_at_iso": "2026-11-10T09:48:28Z"
    },
    "listing.status_changed": {
      "type": "listing.status_changed",
      "id": "evt_1043",
      "created_at": 1794304108,
      "listing": {
        "id": "<listing id>",
        "name": "<listing name>",
        "endpoint_url": "https://api.example.com/v1/route",
        "page": "https://nohumans.directory/l/<listing id>"
      },
      "data": {
        "from": "verified",
        "to": "failing",
        "reason": "probe_fail_streak",
        "changed_at": 1794303900,
        "changed_at_iso": "2026-11-10T09:45:00Z"
      },
      "created_at_iso": "2026-11-10T09:48:28Z"
    },
    "listing.price_changed": {
      "type": "listing.price_changed",
      "id": "evt_1044",
      "created_at": 1794304108,
      "listing": {
        "id": "<listing id>",
        "name": "<listing name>",
        "endpoint_url": "https://api.example.com/v1/route",
        "page": "https://nohumans.directory/l/<listing id>"
      },
      "data": {
        "quote_usd": 0.02,
        "listed_usd": 0.01,
        "changed_at": 1794303780,
        "changed_at_iso": "2026-11-10T09:43:00Z"
      },
      "created_at_iso": "2026-11-10T09:48:28Z"
    },
    "verify_node": "const sig = 'v1=' + crypto.createHmac('sha256', secret).update(req.headers['x-nohumans-timestamp'] + '.' + rawBody).digest('hex'); ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers['x-nohumans-signature']));",
    "verify_python": "sig = 'v1=' + hmac.new(secret.encode(), (ts + '.' + raw_body).encode(), hashlib.sha256).hexdigest(); ok = hmac.compare_digest(sig, signature_header)"
  },
  "no_claim_token": "https://api.nohumans.directory/v1/listings/<id>/claim explains how to get one (it also recovers a lost token)",
  "docs": "https://nohumans.directory/sellers#alerts"
}