Copy page

Automation & management

Webhooks

Webhooks are the contract for sending selected project events to your server. Use them for push-style automation such as tournament-finished announcements, results exports, and operator workflows once webhooks are configured for your project.

Webhook delivery is a beta Management API surface. Endpoint creation and delivery use scoped management tokens, project/environment ownership, endpoint verification, rate limits, and support evidence. Availability can still vary by project configuration and live-mode readiness.

Available events

The v0 allowlist contains one event:

Event	Source	Use it for
tournament.completed	Canonical public TOURNAMENT_COMPLETED platform event	Discord/Slack announcements, results exports, post-event operator workflows

These events are not available in v0: hand.completed, table.player_seated, table.player_unseated. They need separate privacy, identity, consent, and support policy before they are pushed to customer endpoints.

Event shape

The v0 delivery contract is a JSON object with a stable envelope and event-specific data:

Code
{
  "id": "evt_...",
  "type": "tournament.completed",
  "apiVersion": "2026-05-27",
  "createdAt": "2026-05-27T12:00:00.000Z",
  "livemode": false,
  "organizationId": "org_...",
  "projectId": "devproj_...",
  "environment": "test",
  "source": {
    "type": "tournament",
    "id": "..."
  },
  "data": {
    "tournamentId": "...",
    "completedAt": "2026-05-27T12:00:00.000Z"
  },
  "links": {
    "results": {
      "href": "/api/v1/management/tournaments/.../results",
      "method": "GET"
    }
  }
}

The v0 tournament.completed payload intentionally omits raw player identifiers and winner data. Use links.results.href with a server-side management token to fetch the privacy-safe tournament result: winner, standings, payout summary, replay, and proof evidence. The webhook stays a signed trigger and support envelope instead of carrying outcome details directly.

The discovery link is also the reconciliation point between delivery and outcome. For tournament.completed, the linked tournament result verification read is expected to return the same tournament id, completion timestamp, environment, livemode flag, and privacy-safe integrity summary as the signed webhook envelope.

When the tournament result verification read follows a webhook delivery, forward the verified PokerWorks-Event-Id and PokerWorks-Delivery-Id header values on that GET request. The management read echoes those ids in its support object so your logs, support ticket, and PokerWorks delivery evidence all point at the same event.

links.results is required on the maintained beta tournament.completed contract. If it is absent, treat the delivery as contract-invalid and investigate before announcing or exporting results.

Test with the playground

After creating an active test webhook endpoint, trigger the playground completion fixture to receive a signed tournament.completed delivery immediately:

Code
curl https://api.pokerworks.io/api/v1/management/playground/tournament-completion \
  -H "Authorization: Bearer pw_mgmt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "devproj_...",
    "fixture": "completed-six-max-nlhe-v1"
  }'

The token must be allowed to the project and the test environment and include playground:write and tournament_results:read. The fixture uses synthetic tournament data but goes through the normal webhook event, delivery, queueing, signature, and tournament result discovery contracts.

Signing

The delivery implementation signs every delivery with a webhook endpoint secret. Store the secret in a secret manager when it is revealed; it is not shown again.

The signed delivery contract uses these headers:

Header	Meaning
PokerWorks-Event-Id	Immutable event id. Use it for dedupe after signature verification.
PokerWorks-Delivery-Id	Delivery attempt id. Use it for support and retry diagnostics.
PokerWorks-Timestamp	Unix timestamp used in the signature.
PokerWorks-Signature	v1=<hex hmac sha256> signature.
PokerWorks-Webhook-Version	Webhook contract version used for the delivery.

The signature input is:

Code
v1.<timestamp>.<eventId>.<deliveryId>.<raw request body>

Receivers should verify the HMAC over the exact raw request body. Reject timestamps outside your tolerance window and compare signatures in constant time. Before deduping by PokerWorks-Event-Id, verify that the header value matches the signed body id.

Delivery behavior

The delivery contract is at-least-once. Your endpoint should be idempotent.

• 2xx responses mark a delivery successful.
• Network errors, timeouts, 408, 409, 425, 429, and 5xx are retryable.
• Most 3xx and 4xx responses are terminal.
• Retries use exponential backoff with jitter and a bounded retry window.
• Manual replay sends the original event payload with a new delivery id once replay is enabled.

Endpoint rules

Endpoints are scoped to one organization, project, and environment. The implementation must verify new endpoints before they receive game events.

Production endpoints must use HTTPS. The implementation must block outbound delivery to private, loopback, link-local, reserved, and cloud metadata address ranges, and must not follow redirects by default.

Support bundle

When you contact support about a webhook, include:

• webhook event id
• delivery id
• endpoint id
• project id
• environment
• event type
• HTTP status code, if your endpoint returned one
• request id or correlation id, if shown in Console

Related

• Recipes & the automation loop
• Service accounts & management tokens
• Tournament results & verification
• Guide: Automate with a service account
• Discord tournament announcements
• Google Sheets results export
• Versioning & stability