Grundlagen

Idempotenz

Wiederhole eine Anfrage, die Daten ändert, ohne dass sie doppelt ausgeführt wird. Sende einen Idempotency-Key, und Gemlead beantwortet eine Wiederholung mit dem ersten Ergebnis.

Idempotenzschlüssel senden

Füge den Header Idempotency-Key zu jedem POST, PATCH, PUT oder DELETE hinzu. Nimm einen Wert, der für die Operation eindeutig ist, bis zu 255 Zeichen. Eine UUID v4 ist eine gute Wahl.

Bricht die Verbindung ab, bevor du die Antwort bekommst, sende dieselbe Anfrage mit demselben Schlüssel. Gemlead erledigt die Arbeit nur einmal und gibt dir das Ergebnis, so wird ein Webhook-Endpoint nie doppelt erstellt.

Schlüssel werden 24 Stunden lang gespeichert. GET-Anfragen ändern nie Daten und brauchen keinen.

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4f5e-3b0a-4f7e-9d2c-6a8b1e2d4c7f" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot"]
  }'

Wie Gemlead antwortet

Anfrage	Antwort
Gleicher Schlüssel, gleiche Methode, gleicher Pfad und Body, innerhalb von 24 Stunden	Noch einmal die erste Antwort, gleicher Status und Body, mit dem Header `Idempotent-Replayed: true`.
Gleicher Schlüssel, andere Methode, anderer Pfad oder Body	409 `idempotency_error` mit dem Code `idempotency_key_reused`.
Gleicher Schlüssel, während die erste Anfrage noch läuft	409 mit dem Code `idempotency_key_in_use`. Versuche es eine Sekunde später erneut.
Ein Schlüssel mit mehr als 255 Zeichen	400 mit dem Code `idempotency_key_invalid`.

Wann du es erneut versuchen solltest

Bei einem Netzwerkfehler oder Timeout versuche es mit demselben Schlüssel erneut.
Bei einem 500 versuche es nach einer kurzen Pause mit demselben Schlüssel erneut.
Bei einem 400, 401, 403 oder 404 korrigiere die Anfrage und sende sie mit einem neuen Schlüssel.