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.escalated`	Se escala una conversación
`lead.captured`	Se captura un lead nuevo
`lead.created`	Se crea un registro de lead
`lead_form.submitted`	Se envía un formulario de lead
`handoff.requested`	Se solicita el traspaso a un agente humano
`csat.submitted`	Se envía una valoración CSAT
`csat.received`	Se registra un resultado CSAT
`ai.failed`	La IA no logra producir una respuesta
`ticket.created`	Se abre un ticket de soporte
`ticket.resolved`	Se resuelve un ticket de soporte
`contact.created`	Se crea un contacto nuevo
`contact.updated`	Se actualiza un contacto
`contact.merged`	Se fusionan dos contactos
`contact.deleted`	Se elimina un contacto

El formulario de webhook ofrece además Todos los eventos, que suscribe a todos los eventos anteriores (se guarda como el comodín *); un mismo webhook también acepta una lista de nombres de eventos separada por comas.

Configuración

Ve a Dashboard -> Desarrolladores -> 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-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

El digest se calcula sobre <unix_timestamp>.<cuerpo_bruto_de_la_solicitud>, por lo que verificar solo el cuerpo nunca coincidirá. Divida la cabecera por ,, lea los valores t= y v1=, vuelva a calcular el HMAC-SHA256 de t + '.' + rawBody con su webhook secret y compare ambos digests en tiempo constante. Rechace una entrega cuya marca de tiempo tenga más de unos minutos, para que una carga capturada no pueda reproducirse. Nota: Enviar prueba a una URL que no es un webhook guardado se entrega sin firma — no hay secreto con el que firmarla; pruebe su verificación contra un endpoint guardado.

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 -> Desarrolladores -> Claves API -> Crear clave API.
Inclúyela en la cabecera Authorization:

Authorization: Bearer sk_your_api_key_here

> La clave se muestra una sola vez. Crear una clave exige al menos un ámbito (scope) — Crear permanece desactivado hasta que elija uno — y el valor sk_ completo aparece una única vez, en un diálogo que deliberadamente no se cierra con Escape ni al hacer clic fuera. Después solo se conserva el prefijo en forma legible; el resto es un hash bcrypt y no se puede recuperar. Cópiela antes de cerrar el diálogo. Si la pierde, cree una clave nueva y revoque la anterior.

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.