Docs

Webhooks

Receive inbound messages and lifecycle events in real time, and verify their signatures.

Webhooks deliver events to your server as they happen. Create a subscription with POST /v4/webhooks:

curl -X POST https://api.blooio.com/v4/webhooks \
 -H "Authorization: Bearer bl_live_..." \
 -H "Content-Type: application/json" \
 -d '{ "url": "https://example.com/blooio" }'
Try it

The creation response includes a signing_secret once — store it to verify deliveries.

Event payload

Each delivery is a JSON envelope identifying the event, with the resource it relates to in data:

{
 "id": "evt_...",
 "type": "message.received",
 "created_at": 1718000000000,
 "organization_id": "org_...",
 "data": { }
}

Subscriptions registered through the v2 webhook endpoint keep receiving the flat body they were built for:

{
 "event": "message.received",
 "message_id": "msg_...",
 "chat_id": "+15551234567",
 "data": { }
}

Verifying signatures

Each delivery is signed with your signing_secret (HMAC-SHA256) and sent in the X-Blooio-Signature header. Recompute the signature over {timestamp}.{raw_body} and compare it before trusting the payload — see Verify webhook signatures.

Event types

A subscription receives every event type — inbound and outbound message events (received, sent, delivered, failed, read, reactions), polls, groups, and contact card events. Switch on type in your handler to pick out the ones you act on.

Inspect and replay past deliveries with GET /webhooks/{webhookId}/deliveries, or with GET /webhooks/{webhookId}/logs for a subscription registered through the v2 endpoint.