Webhooks & Events

F14.03 6 features Plattform+

I korthet

Webhooks & Events delivers outbound HTTP callbacks for the seven core petanque-domain events — competition.created, competition.completed, result.published, license.issued, license.transferred, ranking.updated, and sanction.created — each signed with HMAC-SHA256, retried with exponential backoff up to five times, captured in a per-subscription delivery log, and replayable on demand from a hardened operator console with synthetic test endpoints.

Så fungerar det

Tenants register endpoints with POST /webhooks, declaring a target URL, an event-type subscription set drawn from the petanque-specific catalog (competition.created, competition.completed, result.published, license.issued, license.transferred, ranking.updated, sanction.created), and a shared secret. The platform stores a SHA-256 hash of the secret and supports rotation by attaching a secondary key with an overlap window so receivers can roll over without dropping signatures. When a domain action commits, the application emits an event onto the internal event bus; a webhook dispatcher fans the event out to all matching subscriptions, serialises a stable JSON envelope (event id, type, tenant, occurred_at, payload), and signs it with HMAC-SHA256 over the raw body using the active secret.

The signature is sent in an X-Signature header alongside an X-Webhook-Id and X-Timestamp to enable replay protection on the receiver side. Delivery failures (non-2xx, timeout, DNS) trigger exponential backoff with up to five attempts on a 10s × n² schedule (10s, 40s, 90s, 160s, 250s), with jitter to avoid thundering herds. Every attempt — successful or not — is appended to the WebhookDeliveryLog with status code, response excerpt, latency, and signature key id; operators can filter by subscription, event type, or status, manually retry failed deliveries with one click, and use the test-endpoint to fire a synthetic event during onboarding.

The catalog is versioned and documented in OpenAPI so receivers can generate typed handlers from the published schema.

Centrala funktioner

Subscription management via POST /webhooks with per-event-type filtering
Petanque-specific catalog of seven domain events covering competitions, results, licenses, rankings, sanctions
HMAC-SHA256 signing with overlap-window secret rotation
Exponential backoff retries (max 5 attempts, 10s × n² schedule)
Per-subscription delivery log with status, latency, and response capture
Manual retry and synthetic test-endpoint for onboarding
Stable JSON envelope versioned in the public OpenAPI schema

I praktiken

A club website wants to refresh its homepage whenever a new competition result lands. The developer registers a webhook subscription to result.published pointing at https://club.example/hooks/results, copies the generated secret into their server's environment, and clicks Send Test. Their handler verifies the X-Signature header against the body using HMAC-SHA256 and returns 200.

A real result published an hour later triggers a delivery; the handler is briefly unavailable so the platform retries after 10s and succeeds. Three weeks later the developer rotates the secret, configures the new value alongside the old in their handler for 24 hours, and confirms in the delivery log that all signatures used the new key id before retiring the old one.

Features i detta subsystem

ID	Status	Funktioner
F14.03.01	Levererad	Webhook configuration (outbound) — POST /webhooks med prenumerationshantering ✅ PL-F1403
F14.03.02	Levererad	Event types — competition.created/completed, result.published, license.issued/transferred, ranking.updated, sanction.created ✅ PL-F1403
F14.03.03	Levererad	Webhook retry med exponential backoff (max 5 försök, 10s×n²) ✅ PL-F1403
F14.03.04	Levererad	HMAC SHA-256-signering med delad hemlighet, secret rotation ✅ PL-F1403
F14.03.05	Levererad	Petanque-specifik händelsekatalog (7 event-typer) ✅ PL-F1403
F14.03.06	Levererad	Webhook delivery log — per-prenumeration, manuell retry, test-endpoint ✅ PL-F1403