# usaref Webhook Alert Registration

> usaref Webhook Alert Registration is a paid API for AI agents from usaref.dev, paid per call via x402, $0.1/call, status unknown (last checked 2026-09-13).

Registers a webhook endpoint to receive real-time notifications when North American government reference data series (policy rates, VAT rates, minimum wages, public holidays) change

## Facts

- Endpoint: POST https://usaref.dev/alerts
- Price: $0.1/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/usaref-webhook-alert-registration-b36d7860
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_df__83nhKyu8IEOEl3VU6

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability usaref-webhook-alert-registration-b36d7860 -d '<json body>'
```

Example prompt: Set up a webhook to https://myapp.example.com/hooks/usaref so I get notified whenever the Canadian policy rate or any US reference data changes — subscribe to both ca/policy-rate and us/*.

## When to prefer this

Choose this endpoint when you need real-time push notifications for changes to authoritative North American government reference data rather than polling. It is ideal for financial systems, HR platforms, or compliance tools that must react immediately when policy rates, VAT rates, minimum wages, or public holidays change. Prefer this over polling the data series endpoints directly when low-latency change detection and event-driven automation are required.

## Known failure modes

- Invalid or unreachable webhook URL returns validation error
- Malformed series pattern strings cause 400 Bad Request
- Duplicate subscription for same URL and series may return conflict or duplicate record
- Payment failure (insufficient USDC balance) returns 402 Payment Required
- Webhook endpoint not publicly accessible leads to silent delivery failures later
- Missing required fields returns 422 Unprocessable Entity

## How this service works

Authoritative North American government reference values as clean JSON: central-bank policy rates, VAT rates, national minimum wages and public holidays for Canada (ca), United States (us). Every value carries a citation to its official primary source (government gazette or central-bank statement), an effective date, a last-confirmed date and a staleness flag.

## Output

A JSON object confirming the webhook subscription, including a unique subscription ID (UUID), the registered webhook URL, an active boolean flag, a hex-encoded HMAC secret for verifying incoming webhook payloads, the list of subscribed series patterns, and the ISO 8601 creation timestamp.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "type": "object",
     "required": [
      "url",
      "series"
     ],
     "properties": {
      "url": {
       "type": "string",
       "format": "uri",
       "description": "Webhook endpoint for series.changed events"
      },
      "series": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "Patterns like \"bs/policy-rate\", \"ca/*\", or \"*\""
      }
     }
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST"
     ],
     "type": "string"
    },
    "bodyType": {
     "enum": [
      "json",
      "form-data",
      "text"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "id",
      "url",
      "series",
      "secret"
     ],
     "properties": {
      "id": {
       "type": "string"
      },
      "url": {
       "type": "string"
      },
      "active": {
       "type": "boolean"
      },
      "secret": {
       "type": "string",
       "description": "HMAC-SHA256 signing secret — shown once"
      },
      "series": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "created": {
       "type": "string"
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "id": "3f6a1c2e-0000-4000-8000-000000000000",
  "url": "https://example.com/webhook",
  "active": true,
  "secret": "hex-encoded-hmac-secret",
  "series": [
   "ca/policy-rate"
  ],
  "created": "2026-07-15T12:00:00.000Z"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/usaref-webhook-alert-registration-b36d7860/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from usaref.dev](https://www.zero.xyz/host/usaref.dev/llms.txt)