# Guide to bundle.social Webhooks: Features and Best Practices

bundle.social is a [social media API](https://bundle.social/social-media-api) with unlimited connected social accounts on every paid plan. One integration publishes to Instagram, TikTok, YouTube, LinkedIn, X, Facebook, Pinterest, Threads, Bluesky and more.

Its webhooks tell your application when a post has gone live or failed, when a social account is connected, changed or removed, and when a team changes. They replace polling the post endpoint for status.

bundle.social also offers DMs and automations, which it turns on per organization on request for paid plans. With them on, your webhooks also receive comments other people leave on your posts and new DMs.

This guide covers how bundle.social webhooks are configured and signed, the events you will receive, where delivery gives up, and the practices that keep a bundle.social receiver from missing post results.

## What are bundle.social webhooks?

In bundle.social, a [webhook](https://info.bundle.social/api-reference/webhooks) is an HTTPS URL you register on your organization, with its own Signing Secret and event filter. Webhooks live at the organization level, so one webhook receives events for every team. An organization can register up to 5 webhooks.

Each event is a JSON `POST` with these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `bundlesocial` |
| `x-signature` | Lowercase hex HMAC-SHA256 of the raw body, keyed with the webhook's Signing Secret |

There's no event ID header and no timestamp header. The signature covers the body only, which affects how you deduplicate and whether you can reject old requests. Both are covered below.

The body is always `{ "type": "...", "data": { ... } }`, where `data` is the same public object the bundle.social REST API returns. Access tokens, refresh tokens and other secrets are never included.

## bundle.social webhook features

| Feature | Details |
| --- | --- |
| Configuration | Dashboard **Organization > Webhooks**, organization owner only |
| Scope | Organization. One webhook covers every team |
| Webhooks | Up to 5 per organization |
| Event filter | Per webhook. An empty filter receives every event type, including ones added later |
| URL | HTTPS only |
| Method | `POST`, JSON body |
| Signature header | `x-signature`, lowercase hex, no prefix |
| Scheme | HMAC-SHA256 of the raw body |
| Secret | One Signing Secret per webhook, a UUID string used as-is as the key |
| Timestamp or replay protection | None |
| Timeout | 15 seconds |
| Success | Any `2xx` response |
| Retries | 3 attempts in total, with exponential backoff from 30 seconds (about 30 seconds, then about 60) |
| Ordering | Not guaranteed. Up to 50 deliveries run in parallel |
| Auto-disable | After 7 days without a successful delivery. The organization owner gets an email and an in-app notification |
| Manual resend | Any event, from the dashboard or the API, as a new delivery with the same payload, within 2 days |
| Delivery log | Per webhook, filterable by status and event type, with HTTP status and response body |
| Event retention | 2 days after delivery. Events still waiting for a delivery attempt are kept until delivered |

## Common events

| Event | Fires when |
| --- | --- |
| `post.published` | A post finished processing. `data.status` is `POSTED` when it went live and `ERROR` when it failed permanently |
| `post.externally-deleted` | An analytics refresh found that a published post was deleted on the platform (TikTok, YouTube, Instagram and Threads). Sent once per post |
| `comment.published` | A comment you sent through bundle.social finished processing, with the same `POSTED` or `ERROR` status |
| `social-account.created` | A social account was connected |
| `social-account.updated` | A social account changed, including a remote disconnection or a failed token refresh |
| `social-account.deleted` | A social account was disconnected or removed |
| `team.created` | A team was created |
| `team.updated` | A team changed, including social accounts added or removed |
| `team.deleted` | A team was deleted |

Organizations with DMs and automations turned on also receive these events:

| Event | Fires when |
| --- | --- |
| `comment.received` | Someone else commented on one of the account's posts on Instagram, Facebook or TikTok |
| `conversation.created` | The first message arrived from a new participant |
| `conversation.updated` | A conversation's status, preview, participant info or unread count changed |
| `conversation.read.updated` | You marked a conversation as read, or the participant read your messages |
| `conversation.message.created` | A new DM was sent or received |
| `conversation.message.updated` | A DM's status changed, or it was edited, unsent or reacted to |

A failed post is still a `post.published` event, so always check `data.status`. When it's `ERROR`, the details are in `data.error`, `data.errors` and `data.errorsVerbose`. Here is a trimmed `post.published` payload for an Instagram post that went live:

```json
{
  "type": "post.published",
  "data": {
    "id": "5b0c3f0e-8a51-4e2f-9b6d-2f7c1e4a9d10",
    "teamId": "c2e7a4b1-3f6d-4c8e-a1b9-7d5e2f0c8a34",
    "organizationId": "9a1d6e3c-2b7f-4a05-8c4e-1f3b6d9e2a57",
    "title": "Product launch",
    "postDate": "2026-11-10T14:00:00.000Z",
    "postedDate": "2026-11-10T14:00:03.512Z",
    "status": "POSTED",
    "data": {
      "INSTAGRAM": {
        "type": "POST",
        "text": "Our new feature is live. Link in bio.",
        "uploadIds": ["e4b81c27-6d3a-4f59-b0e2-8a7c5d1f3e96"]
      }
    },
    "error": null,
    "errors": null,
    "errorsVerbose": null,
    "externalData": {
      "INSTAGRAM": {
        "id": "18043921756012345",
        "permalink": "https://www.instagram.com/p/DExAmPlE123/"
      }
    },
    "retryCount": 0,
    "createdAt": "2026-11-09T09:12:44.201Z",
    "updatedAt": "2026-11-10T14:00:03.530Z",
    "socialAccounts": [
      {
        "socialAccountId": "0d9f4b2a-7e1c-4a36-9f58-3c2b6e8d1a70",
        "externalPostId": "18043921756012345",
        "socialAccount": { "id": "0d9f4b2a-7e1c-4a36-9f58-3c2b6e8d1a70", "type": "INSTAGRAM", "username": "acme.studio" }
      }
    ]
  }
}

```

* `data.id` is the bundle.social post ID, the one returned when you created the post.
* `data.status` tells you whether the post went live.
* `data.externalData.<PLATFORM>` holds the platform's own post ID and permalink once the post is live.
* `data.updatedAt` changes on every state change, which helps with ordering and deduplication.

Full payloads for every event are in bundle.social's [webhooks reference](https://info.bundle.social/api-reference/webhooks). The DM and comment events have their own pages: [DM webhooks](https://info.bundle.social/api-reference/direct-messages/webhooks) and [automation webhooks](https://info.bundle.social/api-reference/automations/webhooks).

## Setting up bundle.social webhooks

Only the organization owner can manage webhooks.

1. In the bundle.social dashboard, open [Organization > Webhooks](https://bundle.social/dashboard/organization/webhooks).
2. Add your URL, for example `https://example.com/webhooks/bundle-social`. It must use HTTPS.
3. Choose the events, or leave the filter empty to receive all of them.
4. Save, then copy the webhook's **Signing Secret** and store it server-side, for example as `BUNDLE_SOCIAL_WEBHOOK_SECRET`.

From the same page you can disable, re-enable or delete a webhook, browse its deliveries and resend any event.

If you use Hookdeck, bundle.social generates the Signing Secret when you save the webhook, so set things up in this order:

1. In Hookdeck, create a connection with a new source of the **bundle.social** source type and your service as the destination. Leave **Source Authentication** turned off for now.
2. Copy the Hookdeck source URL and add it as the webhook URL in bundle.social.
3. Edit the Hookdeck source, turn on **Source Authentication** under **Advanced Source Configuration**, and paste in the Signing Secret from bundle.social (`webhook_secret_key` in the [API](/docs/api)).

From then on, Hookdeck checks `x-signature` on every request to that source.

For local development, the [Hookdeck CLI](/docs/cli) forwards events from the source to a port on your machine. Pass the name you gave the source:

```bash
hookdeck listen 3000 bundle-social

```

If no source with that name exists, the CLI creates a new source instead, so check that the name matches the bundle.social source you set up.

## Securing bundle.social webhooks

If bundle.social delivers to a Hookdeck bundle.social source with the Signing Secret set, Hookdeck verifies `x-signature` for you and doesn't deliver requests that fail. Your service then verifies Hookdeck's own `x-hookdeck-signature` header instead, as described in [Hookdeck webhook signature verification](/docs/authentication#hookdeck-webhook-signature-verification). The code below is for receiving bundle.social webhooks directly, and as a reference for how bundle.social signs them.

To verify a delivery, compute an HMAC-SHA256 of the raw request body with the Signing Secret as the key, encode it as hex, and compare it with `x-signature` in constant time. There's no prefix to strip and no timestamp to include. Use the secret exactly as the dashboard shows it, as a UTF-8 string.

### Node.js (SDK)

bundle.social's Node.js SDK ([`bundlesocial` on npm](https://www.npmjs.com/package/bundlesocial)) verifies the signature and returns the parsed event, or throws.

```javascript
const express = require('express');
const { Bundlesocial } = require('bundlesocial');

// Verification runs locally, so the API key isn't needed to check webhooks.
const bundle = new Bundlesocial(process.env.BUNDLE_SOCIAL_API_KEY);
const app = express();

// express.raw keeps the exact bytes bundle.social signed.
app.post('/webhooks/bundle-social', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    // constructEvent needs the raw body as a string. A Buffer is JSON-serialized and fails.
    event = bundle.webhooks.constructEvent(
      req.body.toString('utf8'),
      req.get('x-signature'),
      process.env.BUNDLE_SOCIAL_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.sendStatus(401);
  }

  // Persist or queue the event, then answer well inside 15 seconds.
  res.sendStatus(200);
});

```

### Node.js

```javascript
const crypto = require('crypto');
const express = require('express');

function verifyBundleSocialSignature(rawBody, signature, secret) {
  // express.raw leaves req.body as {} for other content types, so require a Buffer.
  if (!Buffer.isBuffer(rawBody) || typeof signature !== 'string' || !secret) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  // Compare bytes, not string lengths, so an unexpected header can't make timingSafeEqual throw.
  const received = Buffer.from(signature, 'utf8');
  const computed = Buffer.from(expected, 'utf8');
  return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}

const app = express();

// express.raw keeps the exact bytes bundle.social signed.
app.post('/webhooks/bundle-social', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyBundleSocialSignature(
    req.body,
    req.get('x-signature'),
    process.env.BUNDLE_SOCIAL_WEBHOOK_SECRET
  );
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  // Persist or queue the event, then answer well inside 15 seconds.
  res.sendStatus(200);
});

```

### Python

```python
import hashlib
import hmac
import json
import os

from fastapi import FastAPI, Request, Response

app = FastAPI()

def verify_bundle_social_signature(raw_body: bytes, signature, secret: str) -> bool:
    if not signature or not secret:
        return False
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode("utf-8"), signature.encode("utf-8"))

@app.post("/webhooks/bundle-social")
async def bundle_social_webhook(request: Request):
    # The raw bytes bundle.social signed, before any JSON parsing.
    raw_body = await request.body()
    if not verify_bundle_social_signature(
        raw_body,
        request.headers.get("x-signature"),
        os.environ["BUNDLE_SOCIAL_WEBHOOK_SECRET"],
    ):
        return Response(status_code=401)

    event = json.loads(raw_body)
    # Persist or queue the event, then answer well inside 15 seconds.
    return Response(status_code=200)

```

Hookdeck's bundle.social source type checks the same signature: hex HMAC-SHA256 of the raw body, keyed with the Signing Secret. A request with a missing or wrong signature is marked as failed verification and is not delivered to your destinations.

> **Make bundle.social webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies the `x-signature` header on every delivery, stores each post result and account event, and delivers it to your service with retries you control.

## bundle.social webhook limitations and pain points

### Retries end after about two minutes

**The Problem:** Post results that arrive during a deploy, restart or outage are marked as failed, and your system never learns whether those posts went live.

**Why It Happens:** bundle.social makes 3 attempts: the first, then one about 30 seconds later, then one about 60 seconds after that. With up to 15 seconds per attempt, an event is marked as failed within roughly two minutes. Anything longer than that loses every event sent in the window.

**Workarounds:**

* Use rolling deploys so your endpoint stays up.
* After an outage, fetch the status of the posts scheduled in that window and reconcile.
* Resend failed events from the dashboard or the API within 2 days, before bundle.social deletes the event records.

**How Hookdeck Can Help:** Hookdeck accepts and stores each delivery as it arrives, so bundle.social's first attempt succeeds. Hookdeck then delivers to your service with [automatic retries](/docs/retries) on a schedule you set, and you can [retry many events at once](/docs/retries#retry-many-events) once your fix is out.

### Auto-disable after 7 days, with no replay

**The Problem:** A webhook whose URL stays broken for a week is disabled, and the events created while it was disabled are gone.

**Why It Happens:** If a webhook goes 7 days without a single successful delivery, bundle.social disables it and notifies the organization owner by email and in the dashboard. Events created while it's disabled are never sent to it, and re-enabling it doesn't replay them.

**Workarounds:**

* Watch the delivery log rather than waiting for the notification.
* Re-enable the webhook as soon as your server is back. Re-enabling resets the 7-day window.
* Reconcile the gap through the bundle.social API.

**How Hookdeck Can Help:** With Hookdeck in front, bundle.social only ever delivers to Hookdeck, which answers every delivery, so your bundle.social webhook stays enabled while your own service is down. The failures happen between Hookdeck and your service instead, where they open [issues](/docs/issues) that can alert you, and the events wait to be retried within your plan's [data retention](/docs/hookdeck-basics#data-retention) period.

### 15 seconds to answer

**The Problem:** A handler that does real work before it answers, such as downloading media or writing to several systems, is counted as failed even when it finishes, and the retry sends the same event again.

**Why It Happens:** bundle.social waits 15 seconds for a `2xx`. Anything slower is a failed attempt.

**Workarounds:**

* Verify the signature, persist or queue the event, return `200`, and process it afterwards.

**How Hookdeck Can Help:** Hookdeck acknowledges bundle.social straight away, so your processing time doesn't count against the 15 seconds. You can also [set a max delivery rate](/docs/destinations#set-a-max-delivery-rate) on your destination so a burst of events doesn't overwhelm your service.

### No event ID and no timestamp

**The Problem:** You can't tell a duplicate from a new event by its headers, and you can't reject a captured request for being too old.

**Why It Happens:** bundle.social sends no delivery ID or timestamp header, and the signature covers the body only. Retries and manual resends carry exactly the same payload, and occasionally the same event arrives twice.

**Workarounds:**

* Deduplicate on payload fields, as described in [best practices](#deduplicate-on-payload-fields).
* Keep your writes idempotent, so processing an event twice has no extra effect.

**How Hookdeck Can Help:** A [deduplication](/docs/deduplication) rule can drop repeats before they reach your service, either on the whole payload or on fields you pick, such as `body.type`, `body.data.id` and `body.data.updatedAt`. The window is 1 second to 1 hour, so a manual resend days later still gets through. Keep your handler idempotent either way.

### No secret rotation

**The Problem:** A Signing Secret lasts as long as its webhook, so there's no way to rotate it in place.

**Why It Happens:** Each webhook gets one Signing Secret when it's created, and bundle.social has no rotation option.

**Workarounds:**

* Register a second webhook with the same URL (you can have up to 5).
* Deploy code that accepts either secret.
* Delete the old webhook.

Both webhooks deliver every event during the overlap, which is one more reason to deduplicate.

**How Hookdeck Can Help:** With Hookdeck in front, your services verify Hookdeck's signature, so the bundle.social Signing Secret lives only in the Hookdeck source and not in every service that consumes bundle.social events.

A Hookdeck bundle.social source holds one Signing Secret, so rotation still needs an overlap:

* Create a second bundle.social source in Hookdeck and connect it to the same destination.
* Register a new bundle.social webhook with the new source's URL, and copy its Signing Secret into the new source.
* Delete the old bundle.social webhook, then the old source.

Your services don't change, but they receive each event twice during the overlap, so keep your handler idempotent.

## Best practices

### Verify against the raw body

bundle.social signs the exact bytes it sends. If you parse the JSON and serialize it again, whitespace or key order can change and the check fails. Read the raw body, verify it, and only then parse it:

* **Express:** `express.raw({ type: 'application/json' })` on the webhook route.
* **Next.js route handler:** `await request.text()`.
* **FastAPI:** `await request.body()`.

### Acknowledge fast and process asynchronously

bundle.social waits 15 seconds and counts anything slower as a failure. Verify, persist the event, return `200`, and do the work afterwards. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### Deduplicate on payload fields

With no delivery ID, build the key from the payload:

* **Post and comment results:** `type`, `data.id` and `data.status`.
* **`.created` and `.deleted` events, and `post.externally-deleted`:** `type` and `data.id`.
* **`.updated` events for accounts, teams, conversations and messages:** `type`, `data.id` and `data.updatedAt`.
* **`comment.received`:** `data.comment.id`.

See our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

### Don't rely on order

bundle.social runs up to 50 deliveries in parallel, and retries land after newer events, so an older `social-account.updated` can arrive after a newer one. Store `data.updatedAt` and ignore anything older than what you already have.

### Return 2xx for events you don't handle

A webhook with an empty filter also receives event types bundle.social adds later. Turn on DMs and automations, for example, and comment and DM events start arriving straight away.

A `4xx` for a type you don't recognize counts as a failed delivery and moves the webhook towards auto-disable. Return `200` and ignore the event, or set an event filter.

### Act on account events

bundle.social checks connected Meta accounts (Facebook, Instagram and Threads) every 6 hours. When a check keeps failing, it sends `social-account.updated` with `data.socialAction.details.code` set to a `REMOTE_DISCONNECT_*` value, then `social-account.deleted` once the account is removed. A failed token refresh on any platform sends `social-account.updated` too.

When the event includes `deleteOn`, you have at least 48 hours before the account is removed. Ask your user to reconnect straight away: if they do before `deleteOn`, nothing is removed. For a longer window, raise `deleteAccountAfter` in your organization settings, up to 168 hours (7 days).

## Conclusion

bundle.social signs each delivery with a hex HMAC-SHA256 of the raw body, gives your server 15 seconds to answer, makes 3 attempts within about two minutes, and disables a webhook after 7 days without a successful delivery. A fast endpoint, payload-based deduplication and a reconciliation job cover most of that.

[Hookdeck Event Gateway](https://hookdeck.com) verifies every bundle.social signature and holds each event until your service has processed it, so a long deploy or a slow handler doesn't cost you post results or get your bundle.social webhook disabled.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle bundle.social webhooks reliably in minutes.