Copy page

Automation & management

Tournament results & verification

Tournament results are the completed outcome of a bounded tournament: standings, placements, payouts, status, and public-safe participant facts. Result proof is the verification layer for those results.

The tournament.completed webhook tells your server that a tournament finished; the result-proof read gives your server the privacy-safe winner, standings, payout summary, replay status, and support evidence to announce, export, or verify the result.

Result proof is a trust product, not a claim that PokerWorks invented proof technology. The beta surface gives you a projection-backed, privacy-safe, supportable result artifact that lines up with the signed webhook that announced the tournament completion. Export endpoints wrap the same artifact in a canonical digest-backed envelope so it can be preserved for support or dispute workflows.

When to use it

Use tournament result verification when your integration needs to say more than "a tournament ended":

• post a Discord or Slack result announcement;
• append standings to Google Sheets;
• link a public result page after a hosted tournament;
• reconcile a signed webhook with the result it announced;
• keep support-safe evidence for a webhook delivery.

Do not use this surface for live gameplay decisions, raw player identity, private cards, hand transcripts, deck order, proof secrets, or bot/action automation.

Try it in test mode

Use the developer playground to trigger the full loop without waiting for a real tournament. The playground emits a frozen, synthetic tournament.completed fixture in your test environment, queues deliveries to active test webhook endpoints, and returns the same tournament result DTO your receiver will fetch from links.results.href.

Create a service-account management token scoped to your test project with playground:write and tournament_results:read:

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 response includes the playground tournament id, the queued webhook delivery summaries, the webhook envelope, and a result verification object for the same synthetic tournament. The fixture uses obviously fake player display names and public participant ids; it never reads or exposes real player data.

Endpoints

The management read is the server-side recipe path:

Code
GET /api/v1/management/tournaments/{tournamentId}/results
Authorization: Bearer pw_mgmt_...

The token needs the tournament_results:read scope and must be allowed to read the owning project and environment.

Use the management export when you need a tamper-evident support artifact:

Code
GET /api/v1/management/tournaments/{tournamentId}/results/export
Authorization: Bearer pw_mgmt_...

The export returns the same result-proof body inside a canonical envelope with resultProofId, generatedAt, schemaVersion, canonicalization metadata, and a SHA-256 base64url digest over the envelope without the verification field. When you forward verified webhook ids, the management export may include top-level webhook correlation for support evidence.

The public read is the browser-safe permalink path for explicitly public results:

Code
GET /api/v1/public/tournaments/{tournamentId}/results

The public export is the browser-safe counterpart:

Code
GET /api/v1/public/tournaments/{tournamentId}/results/export

Unknown, private, cross-project, deleted, or unsupported tournaments return the same not-found shape to unauthenticated callers.

The public permalink is a runtime/read companion, not a Management API resource and not a gameplay API. It exposes only the privacy-safe result-proof projection. Public exports omit project ids, webhook event ids, webhook delivery ids, account ids, private cards, deck order, endpoint secrets, and billing details.

Public tournament result verification reads and exports are still governed by Public Data Use And Brand Rules. Use them for the documented result, verifier, support, and announcement workflows; do not treat them as permission to scrape first-party pages, resell hand histories, train models on private room data, or expose support-only evidence.

Public tournament result cache and stale-result behavior follows Public read freshness. Use conditional requests where supported, respect the declared freshness class, and do not poll a public result link as though it were a live table feed.

Verify an export

Use the public verifier when someone gives you a saved export envelope and you want a deterministic browser-safe verdict without a live management token:

Code
POST /api/v1/public/tournament-results/verify
Content-Type: application/json

Code
{
  "envelope": {
    "object": "developer_tournament_results_export"
  }
}

The verifier checks the export schema version, canonicalization metadata, SHA-256 digest against the supplied envelope, deterministic resultProofId, tournament completion summary, trust-mode integrity summary, and projection evidence. It does not refetch live tournament state, replay hands, certify a shuffle, authenticate who generated the envelope, or make a regulated audit claim.

Digest-mismatched, stale-version, or malformed envelopes return a typed verifier verdict with envelopeConsistent: false; an invalid request wrapper returns a normal API validation error. A self-consistent unsigned envelope reports only envelopeConsistent: true with summary.authenticity.status: "not_signed". Signed export authenticity is a follow-up contract. The verifier response never echoes management-only support pivots such as project ids, webhook event ids, or webhook delivery ids.

When evidence.fairness.status is summary_only, the verifier proves only the projection-backed result summary in the export. Hand-level fairness, replay, private cards, raw deck order, and settlement details remain outside this public verifier.

Webhook flow

For tournament.completed, prefer the discovery link in the webhook envelope:

Code
{
  "id": "evt_01JEXAMPLE",
  "type": "tournament.completed",
  "environment": "test",
  "data": {
    "tournamentId": "pw_tournament_01JEXAMPLE000000",
    "completedAt": "2026-06-03T20:42:00.000Z"
  },
  "links": {
    "results": {
      "href": "/api/v1/management/tournaments/pw_tournament_01JEXAMPLE000000/results",
      "method": "GET"
    }
  }
}

Verify the webhook signature over the raw body first, reserve the event/delivery id for idempotency, then fetch links.results.href with your server-side management token. Forward the verified PokerWorks-Event-Id and PokerWorks-Delivery-Id header values on the result/proof request so the response can echo them in support.webhookEventId and support.webhookDeliveryId. Use the /export path when you also need a digest-backed envelope for long-term preservation.

Code
GET /api/v1/management/tournaments/pw_tournament_01JEXAMPLE000000/results
Authorization: Bearer pw_mgmt_...
PokerWorks-Event-Id: evt_01JEXAMPLE
PokerWorks-Delivery-Id: whdel_01JEXAMPLE

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

Example response

Code
{
  "object": "developer_tournament_results",
  "apiVersion": "2026-06-03",
  "environment": "test",
  "livemode": false,
  "tournament": {
    "id": "pw_tournament_01JEXAMPLE000000",
    "displayName": "Wednesday Home Game",
    "status": "completed",
    "completedAt": "2026-06-03T20:42:00.000Z",
    "visibility": "public",
    "productKey": "pokerdeck-club-demo"
  },
  "winner": {
    "rank": 1,
    "displayName": "Alice",
    "publicParticipantId": "pp_AliceResultDemo01"
  },
  "standings": [
    {
      "rank": 1,
      "displayName": "Alice",
      "publicParticipantId": "pp_AliceResultDemo01",
      "finalChips": 120000,
      "payout": {
        "kind": "play_chips",
        "amount": 5000
      },
      "knockouts": 2,
      "bountyWon": 750
    },
    {
      "rank": 2,
      "displayName": "Player 2",
      "publicParticipantId": "pp_PlayerTwoDemo001",
      "finalChips": 0
    }
  ],
  "payoutSummary": {
    "kind": "play_chips",
    "totalAmount": 5000,
    "paidPlaces": 1
  },
  "evidence": {
    "resultProjection": {
      "authority": "TournamentResultsProjectionService",
      "readSurface": "platform.tournament.results",
      "status": "available",
      "projectionSequence": 12345,
      "generatedAt": "2026-06-03T20:42:03.000Z"
    },
    "replay": {
      "status": "available",
      "url": "https://pokerdeck.io/j/ABC123/results"
    },
    "fairness": {
      "status": "summary_only",
      "description": "Hand-level proof status is available only through approved retained hand lookups."
    }
  },
  "support": {
    "requestId": "req_01JEXAMPLE",
    "webhookEventId": "evt_01JEXAMPLE",
    "webhookDeliveryId": "whdel_01JEXAMPLE",
    "projectId": "devproj_01JEXAMPLE"
  }
}

Privacy boundary

The response never includes raw PlayerId, account ids, email addresses, payment ids, private cards, deck order, proof secrets, management settings, or webhook endpoint secrets.

Display identity is limited to the approved tournament display name, a product-approved public alias, or a generated tournament-scoped label such as Player 2.

The management read may include support pivots such as project id, webhook event id, and delivery id. The public permalink omits those management-only fields and serves only explicitly public results.

Verification posture

For beta, verification means the tournament result read is projection-backed, privacy-classified, and consistent with the signed tournament.completed webhook:

• the webhook data.tournamentId matches the tournament id in links.results.href;
• the tournament result verification read returns the same tournament id, completion timestamp, environment, and privacy-safe integrity summary;
• webhook event and delivery ids can be echoed in management support evidence when you forward the verified headers on the tournament result verification request.

Do not treat evidence.fairness.status: "summary_only" as full cryptographic shuffle verification. It means the summary result is backed by the tournament results projection and that hand-level proof status, when available, is exposed only through approved retained replay surfaces.

Hosted verifier pages, downloadable verifier tooling, and signing-key workflows are planned follow-up surfaces. Until those ship, use the result/proof export as the canonical tamper-evident outcome artifact and keep the signed webhook body plus delivery headers in your own logs.

Support bundle

When asking for help with a tournament result verification read, include:

• request id from the result verification response;
• webhook event id and delivery id, if the read came from a webhook;
• project id and environment;
• tournament id;
• whether you used the management read or public read;
• replay and fairness statuses from the evidence object.

Related

• Recipes & the automation loop
• Webhooks
• Service accounts & management tokens
• Discord tournament announcements
• Google Sheets results export
• Calculation API Reference