Webhooks
Receive real-time events via signed webhooks. Messages, presence, read receipts — all delivered to your endpoint.
Configure Webhook URL
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" }'Response includes webhookSecret for verifying signatures. Store it securely — it is returned only once.
Events
| Event | When it fires |
|---|---|
COMPANY_ACTIVATED | Company activated after payment. |
MESSAGE_RECEIVED | A contact sent a message. |
MESSAGE_DELIVERED | Customer's device received a company-sent message. |
MESSAGE_READ | Customer read a company-sent message. |
CUSTOMER_JOINED | Customer opened the link and registered public key. |
CONVERSATION_CLOSED | A conversation was closed. |
TYPING | Customer is typing. |
STOPPED_TYPING | Customer stopped typing. |
RECORDING | Customer is recording audio. |
CHAT_CLOSED | Customer closed the chat window. |
BALANCE_LOW | Company credit balance is running low. |
Event Payload Example
MESSAGE_RECEIVED
{
"event": "MESSAGE_RECEIVED",
"companyId": "660f9511-...",
"conversationId": "880fc844-...",
"messageId": "bb1if177-...",
"sentAt": "2026-09-06T12:00:00.000Z"
}Verifying Signatures
Webhook payloads are signed with HMAC-SHA256. The signature is in the X-Ixblix-Signature header.
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,
);Delivery Guarantees
- Delivery is at-least-once. Deduplicate by
X-Ixblix-Event-Id. - Failed deliveries retry with exponential backoff (up to 8 attempts).
- Respond
2xxquickly. SMCI times out after 10 seconds.
Headers
| Header | Description |
|---|---|
X-Ixblix-Signature | HMAC-SHA256 signature. |
X-Ixblix-Event-Id | Unique delivery ID (for dedup). |
X-Ixblix-Event | Event type. |
X-Ixblix-Company-Id | Company ID (for multi-tenant receivers). |
X-Ixblix-Backend-Id | Backend instance ID that generated the event. |