Basisbegrippen

Idempotentie

Herhaal een request dat gegevens wijzigt zonder dat het twee keer wordt uitgevoerd. Stuur een Idempotency-Key mee en Gemlead beantwoordt een herhaling met het eerste resultaat.

Een sleutel meesturen

Voeg de header Idempotency-Key toe aan elke POST, PATCH, PUT of DELETE. Gebruik een waarde die uniek is voor de bewerking, maximaal 255 tekens. Een UUID v4 is een goede keuze.

Valt de verbinding weg voordat je het antwoord hebt, stuur dan hetzelfde request opnieuw met dezelfde sleutel. Gemlead voert het werk één keer uit en geeft je het resultaat, zodat een webhook-endpoint nooit dubbel wordt aangemaakt.

Sleutels worden 24 uur bewaard. GET-requests wijzigen nooit gegevens en hebben geen sleutel nodig.

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"]
  }'

Hoe Gemlead antwoordt

Request	Antwoord
Zelfde sleutel, zelfde methode, pad en body, binnen 24 uur	Opnieuw de eerste response, met dezelfde status en body, en de header `Idempotent-Replayed: true`.
Zelfde sleutel, andere methode, ander pad of andere body	409 `idempotency_error` met de code `idempotency_key_reused`.
Zelfde sleutel terwijl het eerste request nog loopt	409 met de code `idempotency_key_in_use`. Probeer het een seconde later opnieuw.
Een sleutel langer dan 255 tekens	400 met de code `idempotency_key_invalid`.

Wanneer je het opnieuw probeert

Bij een netwerkfout of een time-out probeer je het opnieuw met dezelfde sleutel.
Bij een 500 probeer je het na een korte pauze opnieuw met dezelfde sleutel.
Bij een 400, 401, 403 of 404 pas je het request aan en stuur je het met een nieuwe sleutel.