Webhooks
Receive Tanitar events at your own HTTPS endpoint as signed, retried, replayable deliveries.
Webhooks push tenant activity to a URL you run, so your systems react without polling. Examples include a tournament starting, a mission completing, a grant applying or a shop order settling.
How it works
- An administrator on your team registers an endpoint (an HTTPS URL) in the Tanitar dashboard and chooses the event types it receives. Tanitar shows the endpoint's signing secret once.
- The endpoint must pass a test delivery before it can be enabled.
- When an event your endpoint subscribes to occurs on your tenant, Tanitar records one
delivery for that endpoint and
POSTs the event to it. - Every delivery is signed with HMAC-SHA256. Your receiver verifies the signature before it trusts the body.
- A delivery that does not get a
2xxanswer is retried on a fixed ladder of eight attempts. One that never succeeds is markeddeadand stays visible in the delivery log. - An administrator can replay a single delivery, or every dead delivery of an endpoint after
an outage. Replays reuse the same
webhook-idand carry atanitar-replayheader.
sequenceDiagram
participant D as Tanitar
participant R as Organizer receiver
D->>R: POST event (webhook-id, webhook-timestamp, webhook-signature)
alt 2xx within the timeout
R-->>D: 200 OK
Note over D: delivery settles as delivered
else error, timeout or non-2xx
R-->>D: 500
Note over D: next attempt scheduled on the retry ladder
end
What you can subscribe to
Only a closed list of event types is exposed to webhooks: rewards, shop, gamification, player membership and tournament events. Internal platform traffic is never delivered. The full list, with the payload of each event and a signed example request, is the event catalog.
Who manages webhooks
Endpoints, subscriptions, secrets and replays are managed from the dashboard by an administrator of
your organization (the org:admin role); every member of the organization can read endpoints and
the delivery log. See Webhooks in the dashboard for the screens.
The webhooks:read, webhooks:mutate and webhooks:replay API-key scopes exist in the scope
catalog, but no webhook route accepts an API key today. Manage webhooks through the dashboard.
Guarantees in one table
| Property | Behavior |
|---|---|
| Delivery | At least once. Deduplicate on webhook-id. |
| Ordering | Not guaranteed. Use occurredAt and the event's own fields to order. |
| Signature | HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<body>, one v1, entry per active secret. |
| Timeout | 10 seconds per attempt by default. Redirects are not followed. |
| Retries | Eight attempts over roughly 45 hours; a 410 Gone stops them at once. |
| Retention | A settled delivery stays in the log for 30 days. |
| Endpoints | Up to 10 non-revoked endpoints per organization. |