DM Webhooks

The fastest way to build an inbox is to let us push changes to you. Webhooks are also how you keep a history longer than our 30-day retention: save every conversation.message.created payload (and apply conversation.message.updated for edits, unsends and status changes) and you have the full thread on your side.

Heads-up: new events arrive as soon as the feature is on. From then on we send your webhook an event for every new DM (conversation.*) and every new comment from other people on posts you published through bundle.social (comment.received, described in Automations). If your webhook has no event filter, you get all of them automatically.Answer every event with a 2xx within 15 seconds, including event types you don’t handle yet. Just ignore them. If your endpoint keeps failing and goes 7 days without a single successful delivery, we disable it automatically. You’ll get an email and a dashboard notification, and you then have to re-enable it (or set up a new one) in the Webhooks dashboard. Events sent while it was disabled are not replayed. More in Webhooks.

Subscribe to these events on your webhook (or leave the event filter empty to get everything):

Event	When it fires	`data` contains
`conversation.created`	First message from a new participant (or first private reply)	Conversation
`conversation.updated`	Status, preview or participant info changed, or a new message raised the unread count	Conversation
`conversation.read.updated`	You marked it as read (unread count reset), or the participant read your messages (`platformSeenAt`)	Conversation
`conversation.message.created`	New message, incoming or outgoing	Message
`conversation.message.updated`	Status changed (`SENT` → `SEEN`…), edited, unsent, or reacted to	Message

Payloads use the same shape as the conversation and message objects from the REST API, wrapped in the usual envelope. One difference: the top-level replyTo and privateReplyContext of a message are only filled in on REST reads. In webhooks, look at platformData.replyTo instead, or fetch the message.

{
  "type": "conversation.message.created",
  "data": {
    "id": "msg_1",
    "conversationId": "conv_abc",
    "teamId": "team_123",
    "socialAccountId": "sa_789",
    "platform": "INSTAGRAM",
    "direction": "INBOUND",
    "status": "DELIVERED",
    "source": "DM",
    "text": "Hi! Do you ship to Poland?",
    "attachments": [],
    "sentAt": "2026-09-26T09:30:00.000Z",
    "platformData": {},
    "createdAt": "2026-09-26T09:30:01.000Z",
    "updatedAt": "2026-09-26T09:30:01.000Z"
  }
}

Example: A Tiny Inbox Handler

Verify the signature, answer fast, do the real work afterwards:

import crypto from "node:crypto";
import express from "express";

const app = express();

// Keep the raw body - the signature is computed over the exact bytes we sent.
app.post("/webhooks/bundle", express.raw({ type: "application/json" }), async (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.BUNDLE_WEBHOOK_SECRET!)
    .update(req.body)
    .digest("hex");
  const received = String(req.headers["x-signature"] ?? "");

  if (
    received.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  ) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.status(200).end(); // ack first, we have 15 seconds

  if (event.type === "conversation.message.created" && event.data.direction === "INBOUND") {
    await saveToInbox(event.data); // your code
    await notifyAgents(event.data.conversationId); // your code
  }

  if (event.type === "conversation.message.updated") {
    await updateMessageStatus(event.data.id, event.data.status); // Messenger: SENT -> DELIVERED -> SEEN, Instagram: SENT -> SEEN
  }
});

Deduplicate on data.id + data.updatedAt. Don’t use status for this: edits, unsends and reactions change a message without changing its status. Retries (ours and Meta’s) can occasionally deliver the same change twice.

Outgoing messages reach your webhook already as SENT or FAILED, never as PENDING.

API Documentation

Platforms

Guides

Endpoints

Example: A Tiny Inbox Handler

​Example: A Tiny Inbox Handler

Example: A Tiny Inbox Handler