Gemlead
Docs
Entrar
Obter sua chave de API

Referência da API

Endpoints de webhook

Um endpoint de webhook é uma URL sua que recebe os eventos do Gemlead no momento em que acontecem. Você pode ter 10 por conta. Leia Webhooks para ver os eventos, os payloads e como verificar uma assinatura.

Endpoints

O objeto webhook endpoint

Uma URL sua para a qual o Gemlead envia eventos. Veja Webhooks para os eventos e como verificá-los.

Atributos

  • idstring
    Identificador único do endpoint.
  • objectstring
    Sempre webhook_endpoint.
  • urlstring
    A URL HTTPS para a qual os eventos são enviados.
  • descriptionstring ou null
    A sua nota sobre o endpoint.
  • eventsarray de strings
    Os tipos de evento enviados para ele.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    Indica se os eventos são enviados para ele.
    enableddisabled
  • filtersobject
    Quais eventos ele recebe, conforme a persona do lead. Os filtros valem para todos os tipos de evento.
  • disabled_reasonstring ou null
    Por que ele está desativado. manual quando você o desativou, failing quando o Gemlead o desativou depois de 3 dias seguidos de falhas e pelo menos 8 tentativas com falha. null enquanto está ativado.
    manualfailing
  • secretstring
    O segredo de assinatura, whsec_ seguido de 32 caracteres. Só aparece nas respostas de criação e de renovação do segredo.
  • created_atstring
    Quando o endpoint foi criado, em ISO 8601.
  • updated_atstring
    Quando o endpoint mudou pela última vez, em ISO 8601.
O objeto webhook endpoint
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Listar endpoints de webhook

GET/v1/webhook_endpointsScope read

Retorna seus endpoints de webhook, sem os segredos.

Parâmetros de consulta

  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos webhook endpoint.

GET/v1/webhook_endpoints
curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "object": "list",
  "data": [
    {
      "id": "wh3LpX9dKe",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/gemlead",
      "description": "CRM sync",
      "events": ["lead.hot", "reply.received"],
      "status": "enabled",
      "filters": {
        "persona_ids": ["lvWBPnytpS"]
      },
      "disabled_reason": null,
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Criar um endpoint de webhook

POST/v1/webhook_endpointsScope write

Cadastra uma URL para um ou mais tipos de evento. Guarde o secret da resposta, pois é a única vez que ele aparece.

Parâmetros do corpo

  • urlstringObrigatório
    Uma URL HTTPS que responde na internet pública.
  • eventsarray de stringsObrigatório
    Os tipos de evento a enviar.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Uma nota para você mesmo.
  • filtersobject
    Quais eventos enviar, conforme a persona do lead.

Retorno

O novo objeto webhook endpoint com o secret dele.

Erros

POST/v1/webhook_endpoints
curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'
Resposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Obter um endpoint de webhook

GET/v1/webhook_endpoints/:idScope read

Retorna um endpoint de webhook, sem o segredo.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Retorno

Um objeto webhook endpoint.

Erros

GET/v1/webhook_endpoints/:id
curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Atualizar um endpoint de webhook

PATCH/v1/webhook_endpoints/:idScope write

Altera um endpoint. Defina status como enabled para reativar um endpoint que o Gemlead desativou. Reativar o endpoint ou dar a ele uma nova url zera a contagem de falhas.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Parâmetros do corpo

  • urlstring
    Uma nova URL HTTPS.
  • eventsarray de strings
    Os tipos de evento a enviar.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Uma nota para você mesmo.
  • statusstring
    Ativa ou desativa o endpoint.
    enableddisabled
  • filtersobject
    Quais eventos enviar, conforme a persona do lead.

Retorno

O objeto webhook endpoint atualizado.

Erros

  • 404resource_missing
    Nenhum endpoint de webhook com este ID na conta da chave.
  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 400url_invalid
    A URL não é HTTPS, contém credenciais ou aponta para um endereço privado.
PATCH/v1/webhook_endpoints/:id
curl -X PATCH \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'
Resposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Excluir um endpoint de webhook

DELETE/v1/webhook_endpoints/:idScope write

Exclui um endpoint. Os envios que ainda esperavam uma nova tentativa são descartados.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Retorno

Um objeto com o id do endpoint e deleted igual a true.

Erros

DELETE/v1/webhook_endpoints/:id
curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

Renovar o segredo de assinatura

POST/v1/webhook_endpoints/:id/roll_secretScope write

Substitui o segredo do endpoint na hora, e o antigo para de funcionar. Os envios que falharem nesse meio-tempo são repetidos, assinados com o novo segredo.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Retorno

O objeto webhook endpoint com o novo secret.

Erros

POST/v1/webhook_endpoints/:id/roll_secret
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/roll_secret \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Enviar um evento de teste

POST/v1/webhook_endpoints/:id/testScope write

Envia um evento de exemplo do primeiro tipo de evento do endpoint, com data.test igual a true e IDs começando com test_. Uma única tentativa, sem repetição.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Retorno

Um objeto webhook delivery com o status e o status_code que o seu endpoint respondeu.

Erros

POST/v1/webhook_endpoints/:id/test
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "dL5qW1zXa8",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
  "event_type": "lead.hot",
  "status": "succeeded",
  "attempts": 1,
  "status_code": 200,
  "error": null,
  "test": true,
  "next_attempt_at": null,
  "last_attempt_at": "2026-11-06T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

O objeto webhook delivery

Um evento enviado a um endpoint, com as tentativas e a última resposta do seu servidor.

Atributos

  • idstring
    Identificador único do envio.
  • objectstring
    Sempre webhook_delivery.
  • endpoint_idstring
    O endpoint para o qual ele foi enviado.
  • event_idstring
    O evento enviado, o id que o seu servidor recebeu.
  • event_typestring
    O tipo do evento.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    pending enquanto restam tentativas, depois succeeded ou failed.
    pendingsucceededfailed
  • attemptsinteger
    As tentativas feitas até agora, no máximo 8.
  • status_codeinteger ou null
    O status HTTP da sua última resposta. null quando não houve resposta, depois de um timeout ou de um erro de conexão.
  • errorstring ou null
    O que deu errado na última tentativa, como o status e o começo da sua resposta, ou um timeout.
  • testboolean
    true para um evento de teste.
  • next_attempt_atstring ou null
    Quando a próxima tentativa está prevista, enquanto pending.
  • last_attempt_atstring ou null
    Quando a última tentativa foi feita.
  • created_atstring
    Quando o envio foi criado, em ISO 8601.
O objeto webhook delivery
{
  "id": "dR7mK2pVn4",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
  "event_type": "reply.received",
  "status": "pending",
  "attempts": 2,
  "status_code": 503,
  "error": "HTTP 503: Service Unavailable",
  "test": false,
  "next_attempt_at": "2026-11-06T08:18:10.000Z",
  "last_attempt_at": "2026-11-06T08:13:10.000Z",
  "created_at": "2026-11-06T08:12:10.000Z"
}

Listar envios

GET/v1/webhook_endpoints/:id/deliveriesScope read

Retorna os envios mais recentes do endpoint, dos mais novos para os mais antigos, com os eventos de teste. Os envios ficam guardados por 30 dias.

Parâmetros de caminho

  • idstringObrigatório
    O ID do endpoint de webhook.

Parâmetros de consulta

  • limitinteger
    Quantos envios retornar, de 1 a 100. O padrão é 25.

Retorno

Uma lista de objetos webhook delivery. Esta lista não tem next_cursor, aumente o limit para ver mais.

Erros

GET/v1/webhook_endpoints/:id/deliveries
curl -G \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/deliveries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d limit=10
Resposta200
{
  "object": "list",
  "data": [
    {
      "id": "dR7mK2pVn4",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
      "event_type": "reply.received",
      "status": "pending",
      "attempts": 2,
      "status_code": 503,
      "error": "HTTP 503: Service Unavailable",
      "test": false,
      "next_attempt_at": "2026-11-06T08:18:10.000Z",
      "last_attempt_at": "2026-11-06T08:13:10.000Z",
      "created_at": "2026-11-06T08:12:10.000Z"
    },
    {
      "id": "dL5qW1zXa8",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
      "event_type": "lead.hot",
      "status": "succeeded",
      "attempts": 1,
      "status_code": 200,
      "error": null,
      "test": true,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-06T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Receba as novidades do Gemlead
direto no seu e-mail.
Assinar
Ao assinar, você aceita a nossa Política de Privacidade e concorda em receber novidades da nossa empresa.
Gemlead
Produto
Começar
Entrar
Para quem
Agentes de IA
Recursos
Preços
Afiliados
FAQ
Recursos
Compradores, 24/7Os quentes primeiro+60% de respostasDMs sob medidaTudo numa caixa sóSeu closer de IAEscale sem limitesAPI, MCP, webhooksPergunte ao Gemlead
Conteúdo
InícioAPIBlog
Jurídico
Termos
Privacidade
© 2026 Gemlead, Inc. Todos os direitos reservados.
Português