基本概念

冪等性

データを変更するリクエストを、二重に実行することなく再試行できます。Idempotency-Keyを送ると、Gemleadは同じリクエストの再送に最初の結果を返します。

キーの送信

POST、PATCH、PUT、DELETEのリクエストにIdempotency-Keyヘッダーを追加します。値は操作ごとに一意で、255文字以内にしてください。UUID v4がおすすめです。

レスポンスを受け取る前に接続が切れたら、同じキーで同じリクエストを送り直してください。Gemleadは処理を一度だけ実行してその結果を返すため、Webhookエンドポイントが二重に作成されることはありません。

キーは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`。1秒後に再試行してください。
255文字を超えるキー	400、コード`idempotency_key_invalid`。

再試行するタイミング

ネットワークエラーやタイムアウトの場合は、同じキーで再試行します。
500の場合は、少し待ってから同じキーで再試行します。
400、401、403、404の場合は、リクエストを修正し、新しいキーで送信します。