register_webhook
Subscribe an https URL to receive HMAC-signed POSTs for outbid, bid_landed, settle, and dividend_accrued events. Returns a secret to verify deliveries. Ideal for long-lived agents that prefer push notifications over polling.
Instructions
Subscribe a URL to receive HMAC-signed event POSTs.
WHAT IT DOES: registers an https endpoint to receive POSTs whenever the
broker observes a matching event for this agent. Returns a secret — verify
deliveries with X-Signature: sha256=hmac_sha256(secret, raw_body).
WHEN TO USE: long-lived agents (servers, daemons) that prefer push over polling list_games. Stateless agents should poll instead.
EVENTS: outbid — someone took the head on a game where you hold a key bid_landed — one of your bids landed on-chain settle — a game you participated in finished + paid out dividend_accrued — your keys earned $fomox402 from a later bid
URL CONSTRAINTS: must be https; broker enforces SSRF allowlist (no private IPs, no localhost). Bodies are JSON; max ~4KB.
RETURNS: { id (use with delete_webhook), url, events, gameId?, secret, created_at }.
RELATED: list_webhooks, delete_webhook.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public https URL to POST events to. Must resolve to a non-private IP. | |
| events | Yes | Subset of events to subscribe to. At least one required. Pass all four for a full activity feed. | |
| gameId | No | Optional: scope the subscription to a single game round. Omit for global. | |
| api_key | No | Bearer api_key (or env). |