Основные понятия

Идемпотентность

Повторяйте запрос, который меняет данные, не выполняя его дважды. Передайте Idempotency-Key, и на повтор Gemlead ответит первым результатом.

Передача ключа

Добавьте заголовок Idempotency-Key к любому POST, PATCH, PUT или DELETE. Используйте значение, уникальное для операции, длиной до 255 символов. UUID v4 подойдёт отлично.

Если соединение оборвалось до того, как пришёл ответ, отправьте тот же запрос с тем же ключом. Gemlead выполнит работу один раз и вернёт её результат, поэтому эндпоинт вебхука никогда не создастся дважды.

Ключи хранятся 24 часа. Запросы GET никогда не меняют данные, и ключ им не нужен.

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

Как отвечает Gemlead

Запрос	Ответ
Тот же ключ, те же метод, путь и тело, в пределах 24 часов	Повтор первого ответа с тем же статусом и телом и с заголовком `Idempotent-Replayed: true`.
Тот же ключ, но другой метод, путь или тело	409 `idempotency_error` с кодом `idempotency_key_reused`.
Тот же ключ, пока первый запрос ещё выполняется	409 с кодом `idempotency_key_in_use`. Повторите через секунду.
Ключ длиннее 255 символов	400 с кодом `idempotency_key_invalid`.

Когда повторять

При сетевой ошибке или тайм-ауте повторите запрос с тем же ключом.
При ошибке 500 повторите запрос с тем же ключом после короткой паузы.
При ошибке 400, 401, 403 или 404 исправьте запрос и отправьте его с новым ключом.