Webhooks y API REST

Conviro ofrece webhooks para recibir notificaciones de eventos en tiempo real y una API REST para acceder mediante programación a todas las funciones de la plataforma.

Webhooks

¿Qué son los webhooks?

Los webhooks envían una solicitud HTTP POST a tu servidor cada vez que se produce un evento concreto en Conviro. Así puedes reaccionar en tiempo real, sin hacer sondeos (polling).

Eventos disponibles

Evento	Cuándo se activa
`message.new`	Se envía un mensaje nuevo (del visitante o del bot)
`session.started`	Comienza una nueva sesión de conversación
`session.closed`	Se cierra una conversación
`session.handoff`	Una conversación se transfiere a un agente humano
`lead.captured`	Se capta un nuevo lead
`contact.created`	Se crea un nuevo contacto
`ticket.created`	Se abre un ticket de soporte
`csat.submitted`	Se envía una valoración CSAT

Configuración

Ve a Dashboard -> Settings -> Webhooks.
Haz clic en Add Webhook.
Introduce la URL de tu endpoint (debe ser HTTPS).
Selecciona los eventos que quieres recibir.
Haz clic en Save.

Seguridad: firma HMAC-SHA256

Cada payload de webhook se firma con HMAC-SHA256 usando tu secreto de webhook. Verifica la firma en tu servidor para asegurar la autenticidad:

X-Conviro-Signature: sha256=<hex_digest>

Compara esta cabecera con el resumen HMAC-SHA256 del cuerpo bruto de la solicitud, calculado con tu secreto de webhook.

Política de reintentos

Si tu endpoint devuelve un código de estado distinto de 2xx, Conviro lo reintenta hasta 3 veces con retroceso exponencial (1 min, 5 min, 30 min).

API REST

Autenticación

Genera una clave de API en Dashboard -> Settings -> API Keys -> Create Key.
Inclúyela en la cabecera Authorization:

Authorization: Bearer sk_your_api_key_here

Endpoints principales

Método	Endpoint	Descripción
GET	`/api/chatbots`	Listar todos los chatbots
GET	`/api/chatbots/:id`	Obtener los detalles de un chatbot
GET	`/api/sessions`	Listar sesiones (con filtros)
GET	`/api/sessions/:id/messages`	Obtener los mensajes de una sesión
POST	`/api/sessions/:id/messages`	Enviar un mensaje a una sesión
GET	`/api/contacts`	Listar contactos
POST	`/api/contacts`	Crear un contacto
GET	`/api/leads`	Listar leads
POST	`/api/leads`	Crear un lead
GET	`/api/analytics/overview`	Obtener el resumen de analítica

Límites de peticiones

Plan Free: 60 peticiones/minuto
Starter: 120 peticiones/minuto
Pro: 300 peticiones/minuto
Growth+: 600 peticiones/minuto

Las cabeceras de límite de peticiones se incluyen en todas las respuestas:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Documentación completa

Visita /developers para consultar la referencia completa de la API con ejemplos de solicitud y respuesta.