Organisation

API & webhooks

Subscribe to the platform's events into your own systems and manage the federation's machine clients (M2M OAuth2). Outgoing calls are always signed; failed deliveries are retried with exponential backoff (max 5 attempts, 10 s × n²).

Subscription	Endpoint URL	Events	Status	Latest delivery
Results → federation site	https://skanebf.se/hooks/petanque	result.published, ranking.updated	active	2 min ago · 200 OK
Licences → member system	https://medlem.skanebf.se/api/hook	license.issued, license.transferred	active	1 h ago · 200 OK
Competitions → calendar partner	https://kalender.nordvik.example/in	competition.created, competition.completed	auto-disabled	8 errors in a row · 24 h 100% errors
Sanctions → integrity partner	https://integrity.betline.example/wh	sanction.created	paused	3 d ago · 200 OK

Actions per row: test (sends a test event) · pause/resume · rotate secret · delete. Auto-disabled = 24 h with 100% errors (too_many_failures) — reactivate after fixing.

New webhook subscription

Name * E.g. Results → federation site Endpoint-URL (HTTPS) * Must respond 2xx within 10 s Events * Multiple choice in the live app — see the catalogue below Shared secret Generated if you leave it empty · used for HMAC signing Active immediately Otherwise it is created paused Sandbox mode Sandbox tenants may only deliver to webhook.site or their own registered URL — never to production partners

Event catalogue — 7 petanque-specific event types

Event	Description
competition.created	New competition published in the calendar
competition.completed	Competition completed, final results locked
result.published	Results published (per round/final)
license.issued	New licence issued
license.transferred	Licence moved between clubs
ranking.updated	Ranking list recomputed
sanction.created	New sanction registered (integrity flow)

State — no subscriptions

📡

No webhooks yet

Create a subscription and events are pushed to your system in real time.

1 482

deliveries (7 days)

99.1 %

successful on the 1st attempt

retried with backoff

in DLQ (requires action)

Time	Subscription	Event	Attempts	Responses	Status
09:41:12	Results → federation site	result.published	1/5	200 OK · 84 ms	delivered
09:38:55	Licences → member system	license.issued	1/5	200 OK · 122 ms	delivered
09:31:02	Competitions → calendar partner	competition.created	5/5	503 · timeout	DLQ
09:12:47	Results → federation site	ranking.updated	2/5	200 OK · 91 ms (after retry 10 s)	delivered
08:58:20	Sanctions → integrity partner	sanction.created	—	paused subscription	skipped

Retry: exponential backoff (base 30 s, up to 8 attempts in the developer flow, 5 in the standard flow). After exhausted attempts the delivery lands in the DLQ. Replay resends with the header X-Petanque-Replay-Of so the recipient can deduplicate. Endpoints are auto-disabled after 24 h with 100% errors.

State — DLQ requires action

⚠

3 deliveries in DLQ for "Competitions → calendar partner"

The endpoint responds 503. The subscription is auto-disabled (too_many_failures). Fix the recipient, reactivate and run replay.

State — loading delivery log

Client	Client id	Scopes	Rate limit	IP allowlist (CIDR)	Status
Member system Nordvik	m2m_5f8a…c2	members:read, licenses:read	600 req/min	193.14.88.0/24	active
Results TV (arena)	m2m_9b1d…e7	results:read, live-scoring:read	1 200 req/min	—	active
Legacy import (one-off)	m2m_2c4f…a9	imports:write	100 req/min	10.0.40.0/28	blocked

Token issuance: POST /auth/m2m/token (OAuth2 client credentials, RFC 6749 §4.4) → ES512 JWT. Secrets are hashed (SHA-256) and can be rotated without interruption.

New M2M client

Name * Who/what uses the client? Scopes * E.g. results:read, licenses:read — least possible Rate limit (req/min) * 1–10,000 · per client, sliding window IP-allowlist (CIDR) Empty = all IPs. E.g. 193.14.88.0/24 Validity period Note

The secret is shown ONCE at creation.

State — client blocked by the abuse guard

⛔

"Legacy import (one-off)" was locked out — rate limit exceeded 40× in 5 min

The abuse guard blocks the client automatically. Lift the block once the cause is investigated, or rotate the secret if it leaked.

Public data (rankings, results, calendar, venue directory) requires no client — third-party developers self-serve keys, sandbox and data products in the developer portal (developer.petanque.life).