Webhooks API

Receive HTTP POST callbacks when events happen — player joins, leaves, game full, or game reset.

Event types

Type	Triggered when
player_joined	A player is added to the event
player_left	A player is removed from the event
game_full	The last active spot is filled (spotsLeft = 0)
game_reset	A recurring event resets its player list

POST /api/events/[id]/webhooks

Subscribe a webhook URL to receive event notifications.

Request body

Field	Type	Required	Description
url	string	Yes	The URL to receive POST callbacks
events	string[]	No	Event types to subscribe to. Empty array = all events
secret	string	No	Shared secret for HMAC-SHA256 signature verification

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

Payload fields by event type

Event type	data fields
player_joined	playerName, isActive, spotsLeft
player_left	playerName, spotsLeft
game_full	playerName, isActive, spotsLeft (always 0)
game_reset	newDateTime (ISO 8601)

Signature verification

If you provided a secret when subscribing, each delivery includes an X-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

Header	Value
Content-Type	application/json
User-Agent	Convocados-Webhook/1.0
X-Webhook-Signature	HMAC-SHA256 (only if secret configured)