API de Webhooks

La API de Webhooks te permite suscribirte a eventos mediante programación. Úsala para disparadores instantáneos al estilo Zapier o para integraciones personalizadas que necesiten notificaciones en tiempo real.

Nota: la API de Webhooks requiere un plan Hobby o superior con facturación activa.

Endpoints

Crear una suscripción

POST /api/v1/webhooks/subscribe

Cuerpo de la solicitud

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Parámetros

Respuesta

Éxito (201):

{
  "id": "subscription-uuid"
}

Ejemplo

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Eliminar una suscripción

DELETE /api/v1/webhooks/subscribe/[id]

Respuesta

Éxito (200): Devuelve una respuesta vacía con estado 200.

Ejemplo

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar agentes

Obtén los agentes disponibles para suscribirte:

GET /api/v1/chatbots

Respuesta

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Payload del webhook

Cuando ocurre un evento, hacemos un POST a tu URL de destino:

Evento de envío de formulario

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

Encabezados

Incluimos estos encabezados en cada entrega:

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Verifica la firma contra el cuerpo de la solicitud en UTF-8 sin procesar, exactamente como llega, antes de analizar el JSON. Consulta Seguridad de webhooks para conocer el procedimiento de firma y el catálogo de payloads.

Requisitos de la URL

Seguridad

En producción, la URL de una suscripción debe usar HTTPS. Fuera de producción también se acepta HTTP, pero solo se permiten URLs http: y https:, y toda URL debe además pasar una verificación de destino público sobre la propia URL, que rechaza localhost y hostnames de loopback similares, direcciones privadas y link-local literales, y los endpoints de metadatos de la nube.

Consulta Seguridad de webhooks para ver la lista completa de restricciones de destino; es la descripción canónica de esta regla.

Validación

La URL se verifica al crear la suscripción; las URLs que no pasan las verificaciones anteriores se rechazan con un error 400 cuyo mensaje menciona el requisito de producción. La verificación examina la URL tal como está escrita: no resuelve hostnames, así que apunta tu suscripción al endpoint público en el que realmente quieres recibir los eventos. En el momento de la entrega, el nombre de host se resuelve una sola vez, todas las direcciones resueltas deben ser públicas y la conexión se fija a esas direcciones: un nombre de host que resuelva a una dirección privada o interna (incluso si cambia entre la resolución y la conexión) nunca se contacta; el intento se registra como target_blocked.

Confiabilidad

Requisitos de respuesta

Tu endpoint debe:

• Devolver un estado 2xx dentro de los 10 segundos
• Manejar entregas duplicadas (ser idempotente)

Manejo de fallos

• Las entregas fallidas se reintentan cinco veces después de la solicitud inicial
• Un evento agotado incrementa una vez la racha de fallos consecutivos
• Al menos 10 eventos agotados en un lapso de siete días desactivan automáticamente una suscripción
• Los propietarios pueden reparar y volver a habilitar las suscripciones desde la configuración de webhooks
• La entrega es "al menos una vez"; usa eventId para lograr idempotencia y no asumas ningún orden

Respuestas de error

Integración con Zapier

Estos endpoints impulsan nuestra integración con Zapier. Cuando conectas Agentkit a Zapier:

1. Zapier llama a /api/v1/auth para verificar tu clave de API
2. Zapier llama a /api/v1/chatbots para listar tus agentes
3. Cuando habilitas un disparador, Zapier llama a /api/v1/webhooks/subscribe
4. Los eventos se entregan a la URL de webhook de Zapier
5. Cuando lo deshabilitas, Zapier llama a DELETE sobre la suscripción

Para integrar sin escribir código, usa Zapier directamente en lugar de estas APIs.

Configura Zapier →

Ejemplo de código

Gestor de suscripciones en Node.js

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Próximos pasos

• Configura la recopilación de leads para generar eventos
• Configura los webhooks desde la interfaz para la configuración desde el panel
• Conéctate a Zapier para más de 5000 integraciones