--- title: "Create Webhook" method: POST path: "/v1/webhooks" tags: ["Webhooks"] --- # Create Webhook `POST /v1/webhooks` ## Request - Base URL: `https://api.puntersedge.online` - URL: `https://api.puntersedge.online/v1/webhooks` - Auth: API key in header `X-API-Key` Subscribe an HTTPS endpoint to signed event pushes. Events that fire on their own: `race.odds_open` (a race's first bookmaker prices landed), `race.result` (a race's result went final, from 2026-10-13) and `arb.opportunity` (a cross-book arb opened). `odds.change` is the event POST /v1/webhooks/{id}/test sends and nothing else does. An unknown event name is a 422 that lists the events that fire, and nothing is created; `market.suspend`, withdrawn on 2026-10-13 because it never fired, is refused the same way. Each delivery is a POST of the JSON payload with `X-PuntersEdge-Event` naming the event and `X-Webhook-Signature: sha256=`, the HMAC-SHA256 of the raw body keyed with the `secret` in this response. The secret is returned once, here (POST /v1/webhooks/{id}/rotate-secret issues a new one when the delivery queue is enabled). Delivery is at-least-once: the same event can arrive more than once, so deduplicate on `event_id` (in the body, and sent as the `X-PuntersEdge-Id` and `Idempotency-Key` headers). There is no ordering guarantee between events. Each delivery carries `X-PuntersEdge-Timestamp`, `X-PuntersEdge-Attempt` and two signatures: `X-Webhook-Signature: sha256=` (HMAC-SHA256 of the raw body with your secret) and `X-PuntersEdge-Signature: t=,v1=` (HMAC-SHA256 of `.`; refuse a `t` more than 5 minutes from now to block replays). Any 2xx answer is success. A 5xx, 408, 429, timeout or connection failure is retried after 1 min, 5 min, 30 min, 2 h, 6 h (6 tries in all, about 8.5 hours), honouring `Retry-After` up to the next step; any other answer is final. After 10 consecutive undeliverable events, or a day of continuous failure, the subscription is paused and the owner is emailed; POST /v1/webhooks/{id}/resume restarts it with the same secret, and POST /v1/webhooks/{id}/replay re-sends what was missed. The delivery log returns the newest 50 rows unless `limit` says otherwise. ## Headers - `X-API-Key` string - `X-RapidAPI-Proxy-Secret` string ## Request body - WebhookCreate - `url` string, required: HTTPS endpoint that receives the POST, on port 443 or 8443. Plain http://, a host that does not resolve, and a host that resolves to a private, loopback, link-local or other non-public address are rejected with 422. At most 5 subscriptions per API key (409 beyond that). - `events` string[]: Events to subscribe to. Three events have live producers: `arb.opportunity` (a cross-book arb opened), `race.odds_open` and `race.result`. `race.odds_open`: the first bookmaker prices for a race just landed — fires once per race, so you can fetch the card on push instead of schedule-polling. Since the early-market lanes of 2026-09-01 it fires HOURS ahead, not minutes: measured over the 48h to 2026-09-03 11:00 UTC, the first price landed a median 10.1h before the jump on AU thoroughbreds, 5.3h on greyhounds, 6.8h on harness - typically overnight or early morning for the day's card, from one or two early books; the full board fills inside about an hour of the jump. `race.result` (from 2026-10-13): a race's result just went `final` — fires once per race, carrying the race (`race_id`, `result_id`, venue, race number, start, country, category), the placings ({position, name, number, horse_ref}), the `dividends` where the settling source declares them, and `source`. `race_id` is the id race.odds_open and /v1/racing/next-to-go carried for the race, and is null on the rare result we could not link to a priced race (10 of 2,038 final results in the 7 days to 2026-10-12); `result_id` is always set. A result goes final once its placings have been stable for 30 minutes, and the event follows within about five minutes of that: measured over the 3 days to 2026-10-12, results went final a median 36 minutes after the advertised start on AU and NZ races (p90 39), 38 on British and Irish thoroughbreds, and about 4 on British and Irish greyhounds, whose source publishes the result already final. It is the same row /v1/racing/results serves, so settle on it exactly as you would on that endpoint. `odds.change` is delivered solely by POST /v1/webhooks/{id}/test. `market.suspend` was withdrawn on 2026-10-13 — it never had a producer — and is now refused with 422. - `min_edge_pct` number, nullable: Only deliver arb.opportunity when the theoretical edge is at least this percentage. Omit for every opportunity. - `sports` string[], nullable: Only deliver events for these sports. Sport keys as returned by GET /v1/sports; racing events (arbs, race.odds_open and race.result) arrive as racing_horse, racing_greyhound or racing_harness. Omit for all sports. ## Response `200` Successful Response - WebhookResponse - `id` string, required - `url` string, required - `events` string[], required - `min_edge_pct` number, nullable - `sports` string[], nullable - `is_active` boolean, required - `created_at` string, nullable, required - `last_delivery_at` string, nullable, required - `failure_count` integer, required - `secret` string, nullable - `delivery_entitled` boolean - `delivery_paused_reason` string, nullable - `paused_at` string, nullable - `paused_reason` string, nullable ## Other responses - `401`: Missing or invalid API key. Send `X-API-Key`. See https://puntersedge.online/developers/errors - `402`: Monthly credit allowance exhausted for this plan. Upgrade at https://puntersedge.online/api/pricing - `403`: Webhook subscriptions are available on Plus, Business, Platform, Scale and Enterprise plans only. Legacy Growth and Pro keys also qualify. - `409`: This key already has 5 subscriptions. - `422`: Validation Error - `429`: Rate limit exceeded for this plan. Honour the `Retry-After` header (seconds) before retrying. See https://puntersedge.online/developers/rate-limits - `500`: Unexpected server error. Safe to retry with backoff. --- [API](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api.md) · [All operations](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/revisions/f35b6aab1946?raw)