Webhooks API

Receive HTTP POST callbacks when things happen — roster changes, game lifecycle, scheduled reminders, RSVP and payment moments. Payloads are lean domain facts; your client renders them.

Event types

Ordering on a recurring cancel

When a recurring event is cancelled, game_reset is deliveredbefore game_cancelled. By the timegame_cancelled arrives, the event's current game is already thenext occurrence — so game_cancelled.dateTime is thecancelled game's start, not the current game's. UsegameId to tell them apart.

POST /api/events/[id]/webhooks

Subscribe a webhook URL to receive event notifications.

Request body

Example

curl -X POST https://convocados.fly.dev/api/events/EVENT_ID/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["player_joined", "game_full"],
    "secret": "my-shared-secret"
  }'

Response

{
  "id": "cmm...",
  "url": "https://example.com/webhook",
  "events": ["player_joined", "game_full"],
  "createdAt": "2026-03-15T13:00:00.000Z"
}

Limits

• Maximum 10 webhooks per event
• Duplicate URLs on the same event return 409

GET /api/events/[id]/webhooks

List all webhook subscriptions for an event.

Response

{
  "webhooks": [
    {
      "id": "cmm...",
      "url": "https://example.com/webhook",
      "events": ["player_joined", "game_full"],
      "createdAt": "2026-03-15T13:00:00.000Z"
    }
  ]
}

DELETE /api/events/[id]/webhooks/[webhookId]

Unsubscribe a webhook.

Example

curl -X DELETE https://convocados.fly.dev/api/events/EVENT_ID/webhooks/WEBHOOK_ID

Response

{ "ok": true }

Webhook payload

When an event occurs, Convocados sends a POST request to your URL with this JSON body:

{
  "event": "player_joined",
  "eventId": "clx...",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-15T13:30:00.000Z",
  "data": {
    "playerName": "Carlos",
    "isActive": true,
    "spotsLeft": 3,
    "actor": "Carlos"
  }
}

Payload fields by event type

Signature verification

If you provided a secret when subscribing, each delivery includes anX-Webhook-Signature header with an HMAC-SHA256 signature:

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

To verify in Node.js:

import { createHmac } from "crypto";

function verify(payload, signature, secret) {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return expected === signature;
}

Delivery & retry

• Timeout: 5 seconds per request
• Retries: up to 5 attempts with exponential backoff (1s, 2s, 4s, 8s, 16s)
• Success: any 2xx response
• Failure: after 5 failed attempts, the delivery is marked as failed

Headers sent