Gemlead
Docs
Iniciar sesión
Obtén tu clave API

Referencia de la API

Endpoints de webhook

Un endpoint de webhook es una URL tuya que recibe los eventos de Gemlead en cuanto ocurren. Puedes tener 10 por cuenta. Lee Webhooks para conocer los eventos, sus payloads y cómo verificar una firma.

Endpoints

El objeto webhook endpoint

Una URL tuya a la que Gemlead envía eventos. Consulta Webhooks para ver los eventos y cómo verificarlos.

Atributos

  • idstring
    Identificador único del endpoint.
  • objectstring
    Siempre webhook_endpoint.
  • urlstring
    La URL HTTPS a la que se envían los eventos.
  • descriptionstring o null
    Tu nota sobre el endpoint.
  • eventsarray de strings
    Los tipos de evento que se le envían.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    Si se le envían eventos.
    enableddisabled
  • filtersobject
    Qué eventos recibe, según el buyer persona del lead. Se aplican a todos los tipos de evento.
  • disabled_reasonstring o null
    Por qué está desactivado. manual si lo desactivaste tú, failing si lo hizo Gemlead tras 3 días seguidos de fallos y al menos 8 intentos fallidos. null mientras está activado.
    manualfailing
  • secretstring
    El secreto de firma, whsec_ seguido de 32 caracteres. Solo en las respuestas de crear y de renovar el secreto.
  • created_atstring
    Cuándo se creó el endpoint, en ISO 8601.
  • updated_atstring
    Cuándo cambió el endpoint por última vez, en ISO 8601.
El 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

Devuelve tus endpoints de webhook, sin sus secretos.

Parámetros de consulta

  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos webhook endpoint.

GET/v1/webhook_endpoints
curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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
}

Crear un endpoint de webhook

POST/v1/webhook_endpointsScope write

Registra una URL para uno o varios tipos de evento. Guarda el secret de la respuesta, es la única vez que lo verás.

Parámetros del cuerpo

  • urlstringObligatorio
    Una URL HTTPS accesible desde internet.
  • eventsarray de stringsObligatorio
    Los tipos de evento que enviar.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Una nota para ti.
  • filtersobject
    Qué eventos enviar, según el buyer persona del lead.

Devuelve

El nuevo objeto webhook endpoint con su secret.

Errores

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

Obtener un endpoint de webhook

GET/v1/webhook_endpoints/:idScope read

Devuelve un endpoint de webhook, sin su secreto.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Devuelve

Un objeto webhook endpoint.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
GET/v1/webhook_endpoints/:id
curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Actualizar un endpoint de webhook

PATCH/v1/webhook_endpoints/:idScope write

Cambia un endpoint. Pon status en enabled para reactivar un endpoint que Gemlead desactivó. Activarlo o darle una nueva url reinicia su recuento de fallos.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Parámetros del cuerpo

  • urlstring
    Una nueva URL HTTPS.
  • eventsarray de strings
    Los tipos de evento que enviar.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    Una nota para ti.
  • statusstring
    Activar o desactivar el endpoint.
    enableddisabled
  • filtersobject
    Qué eventos enviar, según el buyer persona del lead.

Devuelve

El objeto webhook endpoint actualizado.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 400url_invalid
    La URL no es HTTPS, lleva credenciales o apunta a una dirección privada.
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"
  }'
Respuesta200
{
  "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"
}

Eliminar un endpoint de webhook

DELETE/v1/webhook_endpoints/:idScope write

Elimina un endpoint. Los envíos que aún esperan un reintento se descartan.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Devuelve

Un objeto con el id del endpoint y deleted en true.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
DELETE/v1/webhook_endpoints/:id
curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

Renovar el secreto de firma

POST/v1/webhook_endpoints/:id/roll_secretScope write

Reemplaza al instante el secreto del endpoint, y el antiguo deja de funcionar. Los envíos que fallen mientras tanto se reintentan firmados con el nuevo secreto.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Devuelve

El objeto webhook endpoint con su nuevo secret.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
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"
Respuesta200
{
  "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 un evento de prueba

POST/v1/webhook_endpoints/:id/testScope write

Envía un evento de ejemplo del primer tipo de evento del endpoint, con data.test en true e ID que empiezan por test_. Un solo intento, sin reintentos.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Devuelve

Un objeto webhook delivery con el status y el status_code que respondió tu endpoint.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
POST/v1/webhook_endpoints/:id/test
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

El objeto webhook delivery

Un evento enviado a un endpoint, con sus intentos y la última respuesta de tu servidor.

Atributos

  • idstring
    Identificador único del envío.
  • objectstring
    Siempre webhook_delivery.
  • endpoint_idstring
    El endpoint al que se envió.
  • event_idstring
    El evento enviado, el id que recibió tu servidor.
  • event_typestring
    El tipo del evento.
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    pending mientras quedan intentos, luego succeeded o failed.
    pendingsucceededfailed
  • attemptsinteger
    Intentos hechos hasta ahora, 8 como máximo.
  • status_codeinteger o null
    El código de estado HTTP de tu última respuesta. null si no hubo ninguna, tras un timeout o un error de conexión.
  • errorstring o null
    Qué falló en el último intento, como el código de estado y el principio de tu respuesta, o un timeout.
  • testboolean
    true para un evento de prueba.
  • next_attempt_atstring o null
    Cuándo toca el siguiente intento, mientras está en pending.
  • last_attempt_atstring o null
    Cuándo se hizo el último intento.
  • created_atstring
    Cuándo se creó el envío, en ISO 8601.
El 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 envíos

GET/v1/webhook_endpoints/:id/deliveriesScope read

Devuelve los últimos envíos del endpoint, primero los más recientes, eventos de prueba incluidos. Los envíos se guardan 30 días.

Parámetros de ruta

  • idstringObligatorio
    El ID del endpoint de webhook.

Parámetros de consulta

  • limitinteger
    Cuántos envíos devolver, de 1 a 100. 25 por defecto.

Devuelve

Una lista de objetos webhook delivery. Esta lista no tiene next_cursor, aumenta limit para ver más.

Errores

  • 404resource_missing
    No hay ningún endpoint de webhook con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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
Respuesta200
{
  "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
}
Recibe las novedades de Gemlead
directamente en tu bandeja de entrada.
Suscribirme
Al suscribirte aceptas nuestra Política de privacidad y das tu consentimiento para recibir novedades de nuestra empresa.
Gemlead
Producto
Empezar
Iniciar sesión
Para quién
Agentes de IA
Funciones
Precios
Afiliados
FAQ
Funciones
Compradores 24/7Primero los calientes+60% de respuestasDM a medidaUna bandeja para todoTu closer con IAEscala sin límitesAPI, MCP, webhooksPregunta a Gemlead
Recursos
InicioAPIBlog
Legal
Términos
Privacidad
© 2026 Gemlead, Inc. Todos los derechos reservados.
Español