⚽ Convocados Docs GitHub

Webhook + OpenClaw Integration

Push real-time event updates to OpenClaw or any HTTP endpoint using Convocados webhooks.

Overview

Convocados fires webhooks whenever key actions happen on an event — players joining, teams being randomized, or scores being recorded. You can subscribe any URL to receive these payloads, making it easy to integrate with tools like OpenClaw or your own services.

Step 1 — Create a webhook subscription

Register a webhook URL for your event:

curl -X POST https://convocados.fly.dev/api/events/EVENT_ID/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-openclaw-instance.com/hooks/convocados",
    "events": ["player.added", "player.removed", "teams.randomized"]
  }'

The response includes the subscription ID and a secret you can use to verify payloads.

Step 2 — Receive payloads

When a subscribed action occurs, Convocados sends a POST request to your URL with a JSON body:

{
  "event": "player.added",
  "eventId": "clx1abc...",
  "timestamp": "2026-03-15T18:30:00.000Z",
  "data": {
    "player": { "id": "...", "name": "Alice", "isBench": false }
  }
}

Available event types

EventFired when
player.addedA player joins the event
player.removedA player is removed
teams.randomizedTeams are randomized
event.updatedEvent details change
history.createdA game result is recorded

Step 3 — Verify the signature

Each delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with the secret returned when you created the subscription. 

import crypto from 'crypto';

function verifySignature(body: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Step 4 — OpenClaw configuration

In your OpenClaw dashboard:

  1. Go to Integrations → Incoming Webhooks
  2. Create a new webhook receiver and copy the endpoint URL
  3. Use that URL when creating the Convocados webhook subscription (Step 1)
  4. Map the incoming fields to your OpenClaw data model
Tip: You can subscribe multiple URLs to the same event. Each will receive its own independent delivery with retry logic.

Monitoring deliveries

Check delivery status in the Convocados UI under the Integrations accordion on the event page, or query the API directly. Failed deliveries are retried automatically with exponential backoff.

Troubleshooting

← Previous History