Copy page

Recipes

Google Sheets results export

Use this recipe when a club, creator, or operator wants a lightweight tournament results log in Google Sheets without polling.

Status: closed-beta runnable for accounts with webhooks enabled. The v0 event allowlist contains tournament.completed.

Maintained sample: apps/developer-recipe-google-sheets-results.

What you build

• A server endpoint that receives PokerWorks webhook deliveries.
• Signature verification before any side effect.
• Event/delivery dedupe so retries and replays do not append duplicate rows.
• A Google Sheets append call to a sheet you own or manage.

Requirements

• A Console project.
• A service account token stored server-side for creating/managing the webhook endpoint.
• Management scopes: webhook_endpoints:create, webhook_endpoints:read, webhook_deliveries:read, webhook_deliveries:replay.
• A public HTTPS receiver URL.
• A Google account. A normal personal Google account is enough; Google Workspace is not required.
• A Google Cloud project with the Google Sheets API enabled.
• Google credentials stored server-side.
• A spreadsheet shared with the Google credential that will append rows.

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/developer-api/management/webhook-endpoints \
  -H "Authorization: Bearer pw_mgmt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "devproj_...",
    "environment": "test",
    "label": "Google Sheets results",
    "url": "https://bot.example.com/pokerworks/webhooks",
    "eventTypes": ["tournament.completed"]
  }'

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

2. Connect Google Sheets

For deployed/server usage, create a Google Cloud service account, enable the Google Sheets API, and share the target spreadsheet with the service account email. For local personal-account testing, use an OAuth client and refresh token with the Sheets scope. Keep both credential forms server-side.

Set the sample env:

Code
WEBHOOK_SIGNING_SECRET=pwwhsec_...
GOOGLE_SHEETS_SPREADSHEET_ID=...
GOOGLE_SHEETS_RANGE=Results!A1
GOOGLE_SHEETS_VALUE_INPUT_OPTION=RAW
GOOGLE_SHEETS_TIMEOUT_MS=10000
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
# Or use GOOGLE_SERVICE_ACCOUNT_JSON from a secret manager.

RAW is the default value input option so result ids and timestamps are appended exactly as sent. If you opt into USER_ENTERED, the maintained sample prefixes formula-like strings before append so ids and labels are not evaluated as formulas.

3. Verify before appending

Your receiver must verify the raw request body before it appends a row. The signed input is:

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

The event body is intentionally minimal in v0:

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

Row shape

The maintained sample appends:

Code
receivedAt,eventId,deliveryId,tournamentId,tournamentName,completedAt,entries,winner,standing,payout,environment,projectId,livemode

Optional cells stay blank unless those fields already exist in the safe public payload. The v0 payload intentionally omits raw player identifiers, private player data, and winner identity.

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/developer-api/management/webhook-deliveries?projectId=devproj_...&environment=test&status=failed" \
  -H "Authorization: Bearer pw_mgmt_…"

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

Duplicate events and deliveries are ignored after signature verification, so replay does not append a second row for the same event in the maintained single-process sample. The local JSON dedupe store also expires abandoned in-flight reservations after a bounded TTL so a crash before append can be replayed later. Processed ids are retained without automatic compaction; replace the local store with a shared durable store with explicit retention for long-lived or multi-instance deployments.

Security notes

• Keep pwwhsec_…, pw_mgmt_…, Google credential JSON, OAuth refresh tokens, and spreadsheet ids from real users in server-side secrets.
• Verify signatures before dedupe and before parsing event data.
• Dedupe on PokerWorks-Event-Id and PokerWorks-Delivery-Id; deliveries are at-least-once.
• Treat Google append timeouts and connection drops as ambiguous. The sample marks the event processed before returning 503 so retries do not append duplicate rows; reconcile by eventId before clearing dedupe state or replaying to a fresh receiver.
• Do not assume player names, winner details, standings, or payouts are present in v0.
• Rotate the PokerWorks webhook secret if it is exposed.

Related

• Webhooks
• Service accounts & management tokens
• Discord tournament announcements
• Errors & troubleshooting