Copy page

Recipes

Discord tournament announcements

Use this recipe when a club or community wants a Discord channel to announce completed tournaments without polling.

Status: beta runnable for projects with webhooks configured. The v0 event allowlist contains tournament.completed.

Maintained sample: apps/developer-recipe-discord-announcements. Public-clean example: examples/developer-platform/discord-announcements.

What you build

• A server endpoint that receives PokerWorks webhook deliveries.
• Signature verification before any side effect.
• A tournament result verification read after the webhook arrives.
• A Discord webhook call that posts winner, standings, replay/proof status, and support-safe ids.
• Idempotent handling keyed by PokerWorks-Event-Id.

Requirements

• A Console project.
• A service account token stored server-side.
• Management scopes: webhook_endpoints:create, webhook_endpoints:read, webhook_deliveries:read, webhook_deliveries:replay, tournament_results:read, playground:write for test-mode fixture emission.
• A public HTTPS receiver URL.
• A Discord incoming webhook URL stored in your own secret manager.

1. Create the PokerWorks webhook endpoint

Use the Console Webhooks page, or call the management contract from trusted server code with a pw_mgmt_… token:

Code
curl https://api.pokerworks.io/api/v1/management/webhook-endpoints \
  -H "Authorization: Bearer pw_mgmt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "devproj_...",
    "environment": "test",
    "label": "Discord announcements",
    "url": "https://bot.example.com/pokerworks/webhooks",
    "eventTypes": ["tournament.completed"]
  }'

Store the reveal-once pwwhsec_… signing secret immediately. It is not shown again.

2. Trigger the playground fixture

After your receiver is deployed and the test endpoint is active, emit the playground completion fixture. PokerWorks queues a signed tournament.completed delivery to the endpoint you just created, so you can prove the Discord post path without waiting for a real tournament.

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

If you are proving a PokerDeck tournament, publish the tournament first and include the optional tournament target. The webhook and tournament result verification payload stay the same, and the tournament record also gains links.resultsUrl for organiser tooling:

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",
    "tournament": {
      "roomId": "pw_room_...",
      "tournamentId": "pw_tournament_..."
    }
  }'

The fixture is test-only and uses synthetic player display names and public participant ids.

3. Verify before posting

Your receiver must verify the raw request body before it posts to Discord. The signed input is:

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

The event body is intentionally minimal and includes a tournament result verification link:

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/pw_tournament_.../results",
      "method": "GET"
    }
  }
}

After verification and dedupe reservation, call the required links.results.href with the same server-side pw_mgmt_… token. Treat deliveries without the link as contract-invalid instead of deriving a URL from data.tournamentId.

Post only after the tournament result verification read succeeds. If the result projection returns 503, return a retryable 503 without marking the event processed so PokerWorks can retry later. If Discord is down, also return a retryable status so PokerWorks can retry within the bounded retry window.

4. Replay a failed delivery

Use the Console delivery log to inspect and replay failures. If you are automating from trusted server code, call the management delivery contracts:

Code
curl "https://api.pokerworks.io/api/v1/management/webhook-deliveries?projectId=devproj_...&environment=test&status=failed" \
  -H "Authorization: Bearer pw_mgmt_…"

curl https://api.pokerworks.io/api/v1/management/webhook-deliveries/whdel_.../replay \
  -H "Authorization: Bearer pw_mgmt_…" \
  -X POST

Security notes

• Keep pwwhsec_…, pw_mgmt_…, and the Discord webhook URL in server-side secrets.
• Verify signatures before dedupe and before parsing event data.
• Dedupe on PokerWorks-Event-Id; deliveries are at-least-once.
• Read winner details, standings, replay status, and proof status only from the public-safe tournament result DTO.

Related

• Webhooks
• Service accounts & management tokens
• Errors & troubleshooting