Ereignisse abrufen

Ein Strom, zwei Transportwege. Polling ist Pflicht, Webhooks sind eine optionale Ergänzung darüber.

Polling Core

GET /events?cursor=<opaque>&limit=100

{
  "events": [
    { "id": "evt_…", "type": "appointment.created", "data": { … } }
  ],
  "nextCursor": "…",
  "hasMore": false
}

Kein Cursor bedeutet vollständige Nachlieferung. Ein Endpunkt, zwei Aufgaben — damit läuft die Wiederherstellung nach einem Ausfall über denselben Codepfad, der täglich benutzt wird.
Ein Cursor ist mindestens 30 Tage gültig.
Denselben Cursor erneut zu benutzen ist idempotent.
Abrufintervall: mindestens alle 5 Minuten während der Öffnungszeiten der Praxis.

Der teuerste Fehler in dieser ganzen Spezifikation

Ein abgelaufener Cursor liefert 410 Gone — niemals eine leere Seite.

Eine Synchronisierung, die stillschweigend erfolgreich ist und dabei nichts synchronisiert, ist der schlimmste denkbare Ausfall hier: Alles wirkt gesund, Termine kommen nicht an, und niemand erfährt es. Behandeln Sie 410 als Aufforderung zur vollständigen Neusynchronisierung — Aufruf ohne Cursor.

Webhooks Extended

Petla implementiert Standard Webhooks: die Kopfzeilen webhook-id, webhook-timestamp und webhook-signature; HMAC-SHA256 über {id}.{timestamp}.{body}, base64-kodiert, mit dem Präfix v1,.

Zustellung erfolgt mindestens einmal und unsortiert. Deduplizieren Sie über webhook-id; sortieren Sie über version.
Wiederholungen: 5 s · 5 min · 30 min · 2 h · 5 h · 10 h · 24 h. Ein 410 Gone deaktiviert den Endpunkt.
Ein Webhook ist eine Benachrichtigung, keine verbindliche Nutzlast. Holen Sie das aktuelle Objekt ab, statt einem verspätet eingetroffenen Rumpf zu vertrauen.

Achtung

Webhooks ersetzen das Polling nicht. Sie verkürzen die Latenz. Ein Partner mit Webhooks, der nicht mehr abruft, verliert jedes Ereignis, dessen Zustellung endgültig fehlschlägt.

Ereignistypen

appointment.created · appointment.rescheduled · appointment.cancelled · appointment.updated · connection.revoked

Achtung

Offene Aufzählung. Ignorieren Sie, was Sie nicht kennen. Petla darf jederzeit einen Typ ergänzen, ohne dass das eine brechende Änderung ist.

`connection.revoked`

Die Praxis hat die Verbindung bei Petla beendet. Ihr System muss die Aufrufe einstellen; weitere Aufrufe liefern CONNECTION_REVOKED (401). Beendet die Praxis stattdessen bei Ihnen, rufen Sie DELETE /connections/{connectionId} auf.

Nicht tun

Das Trennen einer Verbindung darf auf keiner Seite bereits geschriebene Termine löschen.

Fehler

{
  "code": "SLOT_TAKEN",
  "status": 409,
  "requestId": "K4M2P7RX",
  "fields": { "start": "SLOT_UNAVAILABLE" }
}

code ist eine stabile, maschinenlesbare Kennung. Verzweigen Sie darauf — nie auf den Text.
requestId ist kurz und zitierfähig. Nennen Sie sie in jeder Support-Anfrage — damit findet Petla den Aufruf in den eigenen Protokollen.
4xx nicht unverändert wiederholen. 5xx und Zeitüberschreitungen mit exponentiell wachsendem Abstand wiederholen.