Webhooks
Reciba eventos en tiempo real vía webhooks firmados. Mensajes, presencia, acuses de lectura — todo entregado a su endpoint.
Configurar URL del Webhook
cURL
curl -X PUT https://api.ixblix.app/api/companies/webhook \
-H "X-API-Key: smci_xxxx" \
-H "Content-Type: application/json" \
-d '{ "webhookUrl": "https://mycrm.example.com/ixblix/webhooks" }'La respuesta incluye el webhookSecret para verificar firmas. Almacénelo de forma segura — se devuelve solo una vez.
Eventos
| Evento | Cuándo se dispara |
|---|---|
COMPANY_ACTIVATED | Empresa activada después del pago. |
MESSAGE_RECEIVED | Un contacto envió un mensaje. |
MESSAGE_DELIVERED | El dispositivo del cliente recibió un mensaje de la empresa. |
MESSAGE_READ | El cliente leyó un mensaje de la empresa. |
CUSTOMER_JOINED | El cliente abrió el enlace y registró la clave pública. |
CONVERSATION_CLOSED | Una conversación fue cerrada. |
TYPING | El cliente está escribiendo. |
STOPPED_TYPING | El cliente dejó de escribir. |
RECORDING | El cliente está grabando audio. |
CHAT_CLOSED | El cliente cerró la ventana del chat. |
BALANCE_LOW | El saldo de créditos de la empresa está bajo. |
Ejemplo de Payload
MESSAGE_RECEIVED
{
"event": "MESSAGE_RECEIVED",
"companyId": "660f9511-...",
"conversationId": "880fc844-...",
"messageId": "bb1if177-...",
"sentAt": "2026-09-06T12:00:00.000Z"
}Verificando Firmas
Los payloads de webhook están firmados con HMAC-SHA256. La firma está en el header X-Ixblix-Signature.
TypeScript
import { verifyWebhook, WEBHOOK_SIGNATURE_HEADER } from "@ixblix/sdk-js";
const signature = req.header(WEBHOOK_SIGNATURE_HEADER);
const { event } = verifyWebhook(
req.body,
process.env.IXBLIX_WEBHOOK_SECRET,
signature,
);Garantías de Entrega
- La entrega es at-least-once. Deduplique por
X-Ixblix-Event-Id. - Los fallos se reintentan con backoff exponencial (hasta 8 intentos).
- Responda
2xxrápidamente. ixblix expira después de 10 segundos.
Headers
| Header | Descripción |
|---|---|
X-Ixblix-Signature | Firma HMAC-SHA256. |
X-Ixblix-Event-Id | ID único de entrega (para dedup). |
X-Ixblix-Event | Tipo del evento. |
X-Ixblix-Company-Id | ID de la empresa (para receivers multi-tenant). |
X-Ixblix-Backend-Id | ID de la instancia backend que generó el evento. |