msgbubblesDocs

Webhooks

Webhooks are how messages reach you: replies, edits, delivery and read receipts, reactions, and typing indicators are POSTed to your endpoint as they happen. Each delivery is signed with your webhook’s secret so you can verify it came from msgbubbles.

Register an endpoint

POST/v1/webhooks

Create a webhook
curl -X POST https://api.msgbubbles.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/msgbubbles/events",
    "events": ["message.received", "message.delivered", "message.read"]
  }'

Omit events to subscribe to everything. Pass your own secret (16–200 characters) to sign deliveries with a key you already control, or omit it and we generate a high-entropy whsec_… one. Either way the response’s data includes the signing secret — store it now: a generated secret is returned only at creation and rotation, never on reads. (Webhook deliveries below are signed event payloads, not API responses, so they are not wrapped in the data envelope.)

The url must be a public http(s) endpoint. Private, loopback, and link-local addresses — localhost, 10.x / 192.168.x, the cloud-metadata IP, and the like — are rejected with 400 invalid_url, and a delivery whose host later resolves to one is dropped.

Pass an Idempotency-Key header to make retries safe: a repeated key returns the original webhook (secret included) with 200 instead of registering a duplicate with 201.

Both success responses also include other_webhooks — the endpoints your account already had (secrets omitted), newest first. Every enabled endpoint receives every event, so a non-empty array means each event will now be delivered to more than one place. If that’s not what you wanted, review your endpoints with GET /v1/webhooks and deregister the extra one with DELETE /v1/webhooks/:id. An empty array means the endpoint you just registered is your only one.

Manage endpoints

List your endpoints with GET /v1/webhooks and fetch one with GET /v1/webhooks/:id. Neither ever returns the secret.

Update an endpoint

PATCH/v1/webhooks/:id

Change the delivery url, replace the subscribed events, set a new signing secret, or pause and resume deliveries with enabled. Send only the fields you want to change.

Body for PATCH /v1/webhooks/:id
{ "url": "https://example.com/msgbubbles/events-v2" }    // repoint deliveries
{ "events": ["message.received", "message.reaction"] }   // replace the subscription
{ "secret": "whsec_your_own_signing_key_value" }         // set/replace the signing secret
{ "enabled": false }                                     // pause without deleting

Set or rotate the signing secret

You decide how the secret is set: pass your own secret (16–200 characters) on create or PATCH — the same key you use to change the url — or let msgbubbles generate a whsec_… one. A generated secret is shown only when it’s issued (at creation and on rotation), never on a read, so store it then.

POST/v1/webhooks/:id/rotate-secret

To roll the secret without choosing a value — you never stored it, or it leaked — rotate it: msgbubbles issues a fresh whsec_…, returns it in the response, and signs deliveries with it immediately (setting your own via PATCH takes effect the same way). Roll the new value out to your verifier in the same deploy.

Delete an endpoint

DELETE/v1/webhooks/:id

Deliveries stop right away, and in-flight retries are abandoned.

Events

EventFires when
message.receivedA contact sends you a message (text and/or media).
message.sentAn outbound message went out — fires once, after its text and every attachment were accepted; includes the channel it went out on and sent_at.
message.deliveredThe recipient’s device acknowledged delivery.
message.readThe recipient read the message (read receipts on).
message.editedA message was edited (iMessage or WhatsApp) — the stored message now holds the new body; includes the revised text and edited_at. Also fires as the confirmation of your own /v1/messages/:id/edit landing.
message.failedAn outbound message permanently failed.
message.reactionA contact reacted (tapback or emoji) to one of your messages — includes reaction and a removed flag.
conversation.typingA contact started or stopped typing — includes a typing boolean.
conversation.renamedA group chat’s title changed.
conversation.opted_outA recipient on a shared number replied STOP (or another opt-out keyword). Stop messaging them: further sends return 409 recipient_opted_out. See Opt-outs.
conversation.opted_inA recipient who had opted out replied START or UNSTOP, and you can message them again.
Example: message.received
{
  "type": "message.received",
  "conversation_id": "7f2c9e1b-…",
  "message_id": "0d4b1f3a-…",
  "from": "+15555550123",
  "to": "+18005551111",
  "text": "sounds good!",
  "channel": "imessage",
  "has_attachments": false,
  "created_at": "2026-06-11T18:25:31.000Z"
}

When the message arrived in a group, the payload also carries is_group: true (the field is absent for one-to-one threads). from is always the individual sender, never the group — the group itself is conversation_id; fetch it from GET /v1/chats/:id for the title. The sender is also recorded on the message object’s metadata — sender_handle for iMessage/SMS, sender_jid for WhatsApp — so messages read back later stay attributable.

Example: message.received (in a group)
{
  "type": "message.received",
  "conversation_id": "3a8d2c47-…",
  "message_id": "6e1f9b02-…",
  "from": "+15555550124",
  "to": "+18005551111",
  "text": "who's bringing snacks?",
  "channel": "imessage",
  "has_attachments": false,
  "is_group": true,
  "metadata": { "sender_handle": "+15555550124" },
  "created_at": "2026-06-11T18:25:31.000Z"
}
Example: message.edited
{
  "type": "message.edited",
  "conversation_id": "7f2c9e1b-…",
  "message_id": "0d4b1f3a-…",
  "text": "sounds good — 7pm!",
  "edited_at": "2026-06-11T18:26:02.000Z"
}
Example: message.sent
{
  "type": "message.sent",
  "conversation_id": "7f2c9e1b-…",
  "message_id": "5c3a7d90-…",
  "channel": "sms",
  "sent_at": "2026-06-11T18:21:06.000Z"
}

sent_at is the same value as the message object’s sent_at. channel is the service the message actually went out on — imessage, sms, or whatsapp — and is nullonly in the rare case an iMessage/SMS send couldn’t be attributed to either. message.sentfires once per message: retrying a message that had already gone out doesn’t fire it again. If the channel reports a part of the message failed while the rest was still going out, you get message.failed instead of message.sent. A retry never re-sends a part that already went out, so retrying that message fires message.sent only if the retry still had a part left to send.

Example: conversation.opted_out
{
  "type": "conversation.opted_out",
  "conversation_id": "7f2c9e1b-…",
  "message_id": "9a6c4e21-…",
  "from": "+15555550123",
  "to": "+18005551111",
  "channel": "sms",
  "keyword": "STOP",
  "opted_out_at": "2026-06-11T18:30:12.000Z"
}

from is the recipient who opted out and to is your shared number. message_idis their keyword reply. It doesn’t fire message.received, but GET /v1/messages/:id returns it. keyword is the matched word in uppercase (opt-out arrives as OPT OUT). The opt-out covers all your shared numbers, so treat it as covering that recipient, not just this conversation. conversation.opted_in has the same shape, with opted_in_at in place of opted_out_at. A repeated STOPdoesn’t fire a second event.

Endpoints registered with the default (all) events receive both. Existing endpoints that receive message.received on an account using shared numbers were subscribed to them automatically. Add them to any other endpoint with PATCH /v1/webhooks/:id.

Verifying signatures

Every delivery carries a Stripe-style signature header over the raw body:

X-msgbubbles-Signature: t=<unix-seconds>,v1=<hex>

where v1 = HMAC-SHA256(secret, "<t>.<raw-body>"). Verify before trusting a payload:

  1. Parse t and v1 from the header.
  2. Reject if |now − t| exceeds your replay window (we recommend 300 seconds).
  3. Recompute the HMAC over "<t>.<raw-body>" and compare constant-time against v1.
Node.js verification
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((s) => s.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Compute the HMAC over the raw request body, before any JSON parsing — re-serialized JSON will not match.

Delivery and retries

  • Respond with any 2xx within 10 seconds to acknowledge. Do slow work after acknowledging, not before.
  • Failed deliveries are retried up to 8 attempts spread over roughly a day: the first retries come seconds to minutes apart to ride out a blip, the last are hours apart (5s, 1m, 10m, 1h, 4h, 8h, 12h between attempts). After the final attempt the delivery is marked failed.
  • Deliveries are at-least-once — key your processing on message_id + type to dedupe.
  • Events can arrive out of order. A delivery waiting out its retry backoff doesn’t hold back later events, and a delivery or read receipt can arrive before that message’s message.sent(most often on a message with attachments). Message status only moves forward, so don’t move a message back to sent when its message.sent arrives after message.delivered or message.read. Receipt events carry no timestamp to order by; fetch the message with GET /v1/messages/:id for its current status. message.edited carries edited_at for ordering edits.