Webhooks
Receba eventos em tempo real via webhooks assinados. Mensagens, presença, recibos de leitura — tudo entregue ao seu endpoint.
Configurar URL do 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" }'A resposta inclui o webhookSecret para verificar assinaturas. Armazene-o com segurança — ele é retornado apenas uma vez.
Eventos
| Evento | Quando dispara |
|---|---|
COMPANY_ACTIVATED | Empresa ativada após pagamento. |
MESSAGE_RECEIVED | Um contato enviou uma mensagem. |
MESSAGE_DELIVERED | O dispositivo do cliente recebeu uma mensagem da empresa. |
MESSAGE_READ | Cliente leu uma mensagem da empresa. |
CUSTOMER_JOINED | Cliente abriu o link e registrou a chave pública. |
CONVERSATION_CLOSED | Uma conversa foi fechada. |
TYPING | Cliente está digitando. |
STOPPED_TYPING | Cliente parou de digitar. |
RECORDING | Cliente está gravando áudio. |
CHAT_CLOSED | Cliente fechou a janela do chat. |
BALANCE_LOW | Saldo de créditos da empresa está baixo. |
Exemplo de Payload
MESSAGE_RECEIVED
{
"event": "MESSAGE_RECEIVED",
"companyId": "660f9511-...",
"conversationId": "880fc844-...",
"messageId": "bb1if177-...",
"sentAt": "2026-09-06T12:00:00.000Z"
}Verificando Assinaturas
Payloads de webhook são assinados com HMAC-SHA256. A assinatura está no 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,
);Garantias de Entrega
- A entrega é at-least-once. Deduplique por
X-Ixblix-Event-Id. - Falhas são retentadas com backoff exponencial (até 8 tentativas).
- Responda
2xxrapidamente. O ixblix expira após 10 segundos.
Headers
| Header | Descrição |
|---|---|
X-Ixblix-Signature | Assinatura HMAC-SHA256. |
X-Ixblix-Event-Id | ID único de entrega (para dedup). |
X-Ixblix-Event | Tipo do evento. |
X-Ixblix-Company-Id | ID da empresa (para receivers multi-tenant). |
X-Ixblix-Backend-Id | ID da instância backend que gerou o evento. |