Concetti di base

Idempotenza

Riprova una richiesta che modifica i dati senza eseguirla due volte. Invia una Idempotency-Key e a ogni ripetizione Gemlead risponde con il primo risultato.

Invia una chiave

Aggiungi l'header Idempotency-Key a qualsiasi POST, PATCH, PUT o DELETE. Usa un valore univoco per ogni operazione, fino a 255 caratteri. Un UUID v4 è un'ottima scelta.

Se la connessione cade prima della risposta, invia la stessa richiesta con la stessa chiave. Gemlead esegue il lavoro una volta sola e ti restituisce il suo risultato, così un endpoint webhook non viene mai creato due volte.

Le chiavi vengono conservate per 24 ore. Le richieste GET non modificano mai i dati e non hanno bisogno di una chiave.

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

Come risponde Gemlead

Richiesta	Risposta
Stessa chiave, stesso metodo, path e body, entro 24 ore	Di nuovo la prima risposta, con lo stesso stato e lo stesso body, e l'header `Idempotent-Replayed: true`.
Stessa chiave, ma un altro metodo, path o body	409 `idempotency_error` con il codice `idempotency_key_reused`.
Stessa chiave mentre la prima richiesta è ancora in corso	409 con il codice `idempotency_key_in_use`. Riprova un secondo dopo.
Una chiave più lunga di 255 caratteri	400 con il codice `idempotency_key_invalid`.

Quando riprovare

In caso di errore di rete o timeout, riprova con la stessa chiave.
In caso di 500, riprova con la stessa chiave dopo una breve attesa.
In caso di 400, 401, 403 o 404, correggi la richiesta e inviala con una nuova chiave.