Ereignisse abrufen

Wann abrufen statt empfangen#

• Kasse ohne öffentliche Adresse: ein Programm im Laden hinter einem Router kann keine Webhooks empfangen. Es holt die Ereignisse ab.
• Nachholen: nach einem Ausfall, einem abgeschalteten Webhook oder einem Fehler in deiner Verarbeitung.
• Abgleich: als zweiter Weg neben dem Webhook, der sicherstellt, dass nichts fehlt.

Ereignisse entstehen für jede aktive Verbindung, auch wenn deine App gar keinen Webhook hat.

Abrufen#

GET /events liefert die Ereignisse des Betriebs, die deine Verbindung sehen darf, dazu die app.*-Ereignisse dieser Verbindung, aufsteigend, das älteste zuerst, bis 30 Tage zurück. app.disconnected kommt hier nie an: mit der Trennung enden die Tokens der Verbindung. Eine Trennung erkennst du an 401 und danach invalid_grant beim Erneuern.

Die Antwort ist eine Liste mit data, has_more, next_after und gap. next_after ist der Wert für after, um dort weiterzulesen; er ist immer gesetzt, auch wenn es keine Ereignisse gab. gap: true heißt, dass dein after nicht mehr aufbewahrt war: es können Ereignisse fehlen, gleiche mit GET /orders?updated_since=… und den anderen Listen ab, die du nutzt.

{
  "object": "list",
  "data": [
    {
      "id": "evt_2bf5a9b06b75442a9244e884a1acfc57",
      "object": "event",
      "type": "reservation.updated",
      "created_at": "2026-10-04T17:45:10.410Z",
      "api_version": "2026-10-08",
      "livemode": true,
      "tenant_id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
      "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
      "data": {
        "object": {
          "object": "reservation",
          "id": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
          "code": "R7K2Q9",
          "status": "confirmed",
          "starts_at": "2026-10-10T17:30:00.000Z",
          "duration_minutes": 120,
          "party_size": 4,
          "table_ids": [
            "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
          ],
          "source": "staff",
          "guest_name": "Alex Example",
          "note": "Window seat if possible",
          "created_at": "2026-10-04T12:00:00.000Z",
          "updated_at": "2026-10-04T12:00:00.000Z"
        },
        "previous_status": "pending",
        "changed": [
          "status"
        ]
      }
    }
  ],
  "has_more": false,
  "next_after": "evt_2bf5a9b06b75442a9244e884a1acfc57",
  "gap": false
}

Die Abfrageschleife#

1. 1

   Wo du stehst

   Lies den after-Wert, den du für diese Verbindung gespeichert hast. Bei einer neuen Verbindung nimm latest: ohne after kämen die letzten 30 Tage, auch Ereignisse von vor der Verbindung.

2. 2

   Holen und verarbeiten

   Ereignisse holen und jedes verarbeiten. Die Verarbeitung erkennt Doppelte an der id.

3. 3

   Weitersetzen

   Erst nach der ganzen Seite next_after dauerhaft speichern, je Verbindung.

4. 4

   Weiter oder warten

   Ist has_more wahr, sofort die nächste Seite. Sonst ein paar Sekunden warten.

# A new connection starts now: no events, only next_after. Store it for this connection.
# (Without after you would get the last 30 days, also events from before the connection.)
curl "https://api.flavoso.com/v1/events?after=latest" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Then always from where you stopped: after = next_after of the previous page.
# "gap": true means that after was no longer kept: resync with GET /orders.
curl "https://api.flavoso.com/v1/events?types=order.*,menu.*,store.*,app.*&limit=100&after=evt_2bf5a9b06b75442a9244e884a1acfc57" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Alle 5 bis 30 Sekunden zu fragen, passt bequem in die Anfragegrenze von 120 Anfragen je Minute und Verbindung.

Ein einzelnes Ereignis#

GET /events/{id} liefert ein Ereignis, etwa um eine Kennung aus dem Webhook-Protokoll nachzusehen.

curl https://api.flavoso.com/v1/events/evt_2bf5a9b06b75442a9244e884a1acfc57 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Derselbe Umschlag#

Ein abgerufenes Ereignis ist derselbe Umschlag wie im Webhook: dieselbe id, dieselben Felder, dasselbe data, beim ersten Lesen oder Versand eingefroren. Wer beides benutzt, erkennt Doppelte an der id. Die Signatur gibt es nur beim Webhook; beim Abruf beweist das Token, wer fragt.

Aufbewahrung#

Ereignisse werden 30 Tage aufbewahrt. Was älter ist, holst du über die Listen nach, etwa GET /orders mit updated_since. Ein älteres after ist kein Fehler: die Antwort macht beim ältesten aufbewahrten Ereignis weiter und sagt gap: true.