Polling-Endpoints

Ein Polling-Endpoint liefert Ihnen denselben Event-Stream wie ein Webhook-Endpoint, aber Sie holen ihn per GET-Request ab, statt dass storekit an eine öffentliche URL pusht. Jeder Poll liefert einen Batch von Nachrichten in der Reihenfolge ihres Eingangs. Sie verarbeiten den Batch, committen, wie weit Sie gekommen sind, und der nächste Poll setzt an dieser Stelle fort.

Wann Polling sinnvoll ist

Polling eignet sich für Fälle, in denen ein öffentlicher HTTPS-Endpoint unpraktisch oder unnötig ist:

Lokale Entwicklung: Pollen Sie vom Laptop aus, ohne ngrok oder Tunnel
Private Netzwerke: Der konsumierende Dienst darf aus dem Internet nicht erreichbar sein
Batch-Verarbeitung: Sie möchten alle Events des Tages auf einmal, etwa um Bestellungen zur Compliance-Archivierung zu sichern oder Auszahlungen über Nacht abzugleichen
Systeme, die kein HTTP empfangen können: ein Cronjob, eine Datenpipeline oder ein Skript

Wenn Sie Events innerhalb von Sekunden nach ihrem Eintreten benötigen, verwenden Sie einen regulären Webhook-Endpoint. Polling- und Webhook-Endpoints können parallel auf demselben Account laufen, gefiltert auf dieselben oder unterschiedliche Event-Typen.

Einen Polling-Endpoint anlegen

Öffnen Sie die Webhook-Seite (Einstellungen → Entwickler → Manage Webhooks)
Fügen Sie im eingebetteten Webhook-Portal einen neuen Endpoint hinzu und wählen Sie den Typ Polling-Endpoint
Wählen Sie die Event-Typen aus, die Sie empfangen möchten
Speichern Sie den Endpoint

Das Portal zeigt Ihnen anschließend zwei Angaben, die Sie für jeden Request benötigen:

Wert	Beispiel	Beschreibung
Polling-URL	`https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/{consumer_id}`	Eindeutig für diesen Endpoint. Kopieren Sie sie exakt wie angezeigt (der Host hängt von der Region ab) und ersetzen Sie `{consumer_id}` durch Ihren eigenen Bezeichner
API-Key	`sk_poll_*****`	Wird als Bearer-Token gesendet. Wird nur einmal angezeigt, sicher aufbewahren

Der API-Key gewährt Lesezugriff auf jedes Event, das der Endpoint abonniert hat, einschließlich Kundennamen und Kontaktdaten in Bestell-Payloads. Behandeln Sie ihn wie jedes andere Produktions-Secret.

Events pollen

Senden Sie einen GET-Request an die Polling-URL mit Ihrem API-Key:

curl -X GET "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer sk_poll_*****"

Die Antwort ist ein Batch von Nachrichten. Der payload jeder Nachricht ist exakt der JSON-Body, den ein Webhook-Endpoint erhalten würde, also der { event, data }-Envelope aus dem Payload-Format, umgeben von Nachrichten-Metadaten und einem offset:

{
  "data": [
    {
      "id": "msg_2K2N9Qk...",
      "eventType": "order.created",
      "payload": {
        "event": "order.created",
        "data": {
          "id": 123456,
          "status": "created",
          "venue": { "id": 789, "name": "Pizza Palace" },
          "total": 2450
        }
      },
      "timestamp": "2025-01-17T12:00:00.000Z",
      "offset": 0
    }
  ],
  "done": true
}

Feld	Beschreibung
`data`	Nachrichten in der Reihenfolge ihres Eingangs. Leer, wenn nichts Neues vorliegt
`data[].payload`	Der Webhook-Body: `payload.event` benennt das Event, `payload.data` enthält die Event-Daten
`data[].offset`	Position der Nachricht im Stream. Committen Sie diesen Wert nach der Verarbeitung
`done`	`true`, wenn dieser Batch das Ende des Streams erreicht hat; `false` bedeutet, sofort erneut pollen, um weitere Nachrichten abzuholen

Signaturprüfung entfällt, da der Request per API-Key authentifiziert wird und nicht als signierte Zustellung.

Ihre Position committen

Nach der Verarbeitung eines Batches committen Sie den offset der letzten verarbeiteten Nachricht:

curl -X POST "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive/commit" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_poll_*****" \
  -d '{ "offset": 0 }'

Solange Sie nicht committen, werden dieselben Nachrichten nach Ablauf ihres Lease erneut ausgeliefert. Das ist Absicht: Stürzt Ihr Worker mitten im Batch ab, geht nichts verloren. Das bedeutet aber auch, dass Ihr Handler idempotent sein muss, siehe Idempotenz.

Consumer-IDs

Die {consumer_id} in der URL ist eine von Ihnen gewählte Zeichenkette. Jede Consumer-ID verfolgt ihre eigene Position im Stream, sodass zwei Consumer, die denselben Endpoint lesen, jeweils jedes Event erhalten.

Verwenden Sie eine stabile ID pro Worker (kitchen-archive, finance-reconciliation), damit der Fortschritt Neustarts übersteht
Teilen Sie niemals eine Consumer-ID zwischen gleichzeitig laufenden Clients. Zwei Prozesse, die als derselbe Consumer pollen, driften im Stream auseinander und die API gibt Fehler zurück

Der Stream beginnt mit dem Anlegen des Polling-Endpoints. Zuvor gesendete Events sind nicht enthalten.

Ein typischer Polling-Loop

const URL = process.env.STOREKIT_POLL_URL;   // includes your consumer id
const KEY = process.env.STOREKIT_POLL_KEY;

async function pollOnce() {
  let done = false;
  while (!done) {
    const res = await fetch(URL, {
      headers: { Accept: 'application/json', Authorization: `Bearer ${KEY}` },
    });
    const body = await res.json();

    for (const msg of body.data) {
      await handleEvent(msg.payload.event, msg.payload.data);
    }

    if (body.data.length > 0) {
      const last = body.data[body.data.length - 1];
      const commit = await fetch(`${URL}/commit`, {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: `Bearer ${KEY}`,
        },
        body: JSON.stringify({ offset: last.offset }),
      });
      if (!commit.ok) throw new Error(`Commit failed: ${commit.status}`);
    }

    done = body.done;
  }
}

Führen Sie pollOnce() in dem Takt aus, der passt: alle paar Sekunden für Near-Realtime oder einmal pro Nacht für einen täglichen Export.

Weiterleitung an einen privaten Dienst

Wenn Sie lieber bei einer Webhook-artigen HTTP-Zustellung bleiben möchten, Ihr Dienst aber in einem privaten Netzwerk läuft, betreiben Sie Svix Bridge innerhalb dieses Netzwerks. Bridge pollt den Endpoint und leitet jede Nachricht an eine interne URL, an RabbitMQ oder Kafka weiter, inklusive Wiederholungen, wenn eine der beiden Seiten vorübergehend nicht erreichbar ist. Die Seite des Polling-Endpoints im eingebetteten Portal enthält eine Starter-Konfiguration für Bridge, in der App-ID und Endpoint-ID bereits eingetragen sind.

Webhooks einrichten

Push-Zustellung an einen öffentlichen HTTPS-Endpoint

Idempotenz

Dasselbe Event sicher mehrfach verarbeiten

Webhook-Events

Jeder Event-Typ, den Sie abonnieren können

Webhooks testen

Zustellungen prüfen und Test-Events versenden

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Polling-Endpoints

Wann Polling sinnvoll ist

Einen Polling-Endpoint anlegen

Events pollen

Ihre Position committen

Consumer-IDs

Ein typischer Polling-Loop

Weiterleitung an einen privaten Dienst

Verwandte Themen

Webhooks einrichten

Idempotenz

Webhook-Events

Webhooks testen

​Wann Polling sinnvoll ist

​Einen Polling-Endpoint anlegen

​Events pollen

​Ihre Position committen

​Consumer-IDs

​Ein typischer Polling-Loop

​Weiterleitung an einen privaten Dienst

​Verwandte Themen

Webhooks einrichten

Idempotenz

Webhook-Events

Webhooks testen

Wann Polling sinnvoll ist

Einen Polling-Endpoint anlegen

Events pollen

Ihre Position committen

Consumer-IDs

Ein typischer Polling-Loop

Weiterleitung an einen privaten Dienst

Verwandte Themen