Events lückenlos konsumieren

Mindestens einmal

Webhooks und WebSockets können dasselbe Event mehrfach liefern. Dedupliziere anhand von id in einer dauerhaften Inbox mit Unique Constraint. Committe Inbox-Zeile, fachliche Wirkung und Replay-Cursor in derselben Datenbanktransaktion.

Event-Envelope

publication_sequence ist die kanonische organisationslokale Reihenfolge und wird als Dezimalstring übertragen. Parse sie als BigInt oder Python int. sequence ordnet nur Events derselben Resource.

{
  "id": "018f5f21-5b62-7a08-8d4c-bc61d6b19a01",
  "type": "booking.updated",
  "schema_version": 1,
  "occurred_at": "2030-01-15T17:52:11.004Z",
  "organization_id": "org_01JABC",
  "resource": {"type":"bookings","id":"bkg_01JABC"},
  "publication_sequence": "9007199254740993",
  "sequence": 4,
  "changed_fields": ["scheduled_start"],
  "data_url": "/v1/club/bookings/bkg_01JABC"
}

Eventtypen

• booking.created · booking.updated · booking.cancelled
• booking.reconciliation_required
• session.created · session.status_changed
• participant.updated
• match.started · match.completed
• score.updated · score.corrected
• court.status_changed

Replay-First Reconnect

• Lies mit GET /events?after=<last-processed-event-uuid> alle verpassten Events.
• Erzeuge mit POST /event-stream-tickets ein einmaliges Ticket.
• Verbinde innerhalb von 60 Sekunden ohne Bearer-Header auf den gelieferten WebSocket.
• Speichere eine Event-ID erst nach erfolgreicher fachlicher Verarbeitung.
• Replaye nach Abbruch oder spätestens nach 60 Minuten und verbinde mit neuem Ticket.

POST /v1/club/event-stream-tickets
Authorization: Bearer <token>
Idempotency-Key: 018f-stream-ticket
Content-Type: application/json

{"after":"018f5f21-5b62-7a08-8d4c-bc61d6b19a01"}

Kontrollframes und Close-Codes

Grenzen

• Events: sieben Tage abrufbar
• Ticket: einmalig, 60 Sekunden gültig
• Verbindung: höchstens 60 Minuten
• Parallele WebSockets: höchstens fünf pro Installation und Club