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 the closed-beta delivery surface is enabled for your account.

Webhook delivery is a closed-beta management-plane surface, not generally available. The contract is defined here so beta integrations build against the right event shape; endpoint creation and delivery are enabled only where the Console/API has the webhook feature switched on.

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"
  }
}

The v0 tournament.completed payload intentionally omits raw player identifiers. If winner identity is added later, it will use a customer-safe external identity projection rather than raw internal player ids.

Signing

The beta delivery implementation must sign 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>

Beta 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 beta implementation must verify new endpoints before they receive game events.

Production endpoints must use HTTPS. The beta 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

• Service accounts & management tokens
• Guide: Automate with a service account
• Discord tournament announcements
• Google Sheets results export
• Versioning & stability