Conceitos básicos

Idempotência

Repita uma requisição que altera dados sem executá-la duas vezes. Envie uma Idempotency-Key, e o Gemlead responde à repetição com o resultado da primeira.

Enviar uma chave

Adicione o cabeçalho Idempotency-Key a qualquer POST, PATCH, PUT ou DELETE. Use um valor único para a operação, de até 255 caracteres. Um UUID v4 é uma boa escolha.

Se a conexão cair antes de você receber a resposta, envie a mesma requisição com a mesma chave. O Gemlead faz o trabalho uma vez só e devolve o resultado, então um endpoint de webhook nunca é criado duas vezes.

As chaves ficam guardadas por 24 horas. Requisições GET nunca alteram dados e não precisam de chave.

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

Como o Gemlead responde

Requisição	Resposta
Mesma chave, mesmo método, caminho e corpo, dentro de 24 horas	A primeira resposta de novo, com o mesmo status e o mesmo corpo, e o cabeçalho `Idempotent-Replayed: true`.
Mesma chave, outro método, caminho ou corpo	409 `idempotency_error` com o código `idempotency_key_reused`.
Mesma chave enquanto a primeira requisição ainda está em execução	409 com o código `idempotency_key_in_use`. Tente de novo um segundo depois.
Uma chave com mais de 255 caracteres	400 com o código `idempotency_key_invalid`.

Quando tentar de novo

Um erro de rede ou um timeout, tente de novo com a mesma chave.
Um 500, tente de novo com a mesma chave após uma breve espera.
Um 400, 401, 403 ou 404, corrija a requisição e envie de novo com uma nova chave.