Gareth Wilson Gareth Wilson

Guide to bundle.social Webhooks: Features and Best Practices

Published · Updated


bundle.social is a 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 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:

HeaderValue
Content-Typeapplication/json
User-Agentbundlesocial
x-signatureLowercase 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

FeatureDetails
ConfigurationDashboard Organization > Webhooks, organization owner only
ScopeOrganization. One webhook covers every team
WebhooksUp to 5 per organization
Event filterPer webhook. An empty filter receives every event type, including ones added later
URLHTTPS only
MethodPOST, JSON body
Signature headerx-signature, lowercase hex, no prefix
SchemeHMAC-SHA256 of the raw body
SecretOne Signing Secret per webhook, a UUID string used as-is as the key
Timestamp or replay protectionNone
Timeout15 seconds
SuccessAny 2xx response
Retries3 attempts in total, with exponential backoff from 30 seconds (about 30 seconds, then about 60)
OrderingNot guaranteed. Up to 50 deliveries run in parallel
Auto-disableAfter 7 days without a successful delivery. The organization owner gets an email and an in-app notification
Manual resendAny event, from the dashboard or the API, as a new delivery with the same payload, within 2 days
Delivery logPer webhook, filterable by status and event type, with HTTP status and response body
Event retention2 days after delivery. Events still waiting for a delivery attempt are kept until delivered

Common events

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

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

EventFires when
comment.receivedSomeone else commented on one of the account's posts on Instagram, Facebook or TikTok
conversation.createdThe first message arrived from a new participant
conversation.updatedA conversation's status, preview, participant info or unread count changed
conversation.read.updatedYou marked a conversation as read, or the participant read your messages
conversation.message.createdA new DM was sent or received
conversation.message.updatedA 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:

{
  "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. The DM and comment events have their own pages: DM webhooks and automation webhooks.

Setting up bundle.social webhooks

Only the organization owner can manage webhooks.

  1. In the bundle.social dashboard, open 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).

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

For local development, the Hookdeck CLI forwards events from the source to a port on your machine. Pass the name you gave the source:

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. 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.

bundle.social's Node.js SDK (bundlesocial on npm) verifies the signature and returns the parsed event, or throws.

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);
});
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);
});
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 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 on a schedule you set, and you can retry many events at once 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 that can alert you, and the events wait to be retried within your plan's 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 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.
  • Keep your writes idempotent, so processing an event twice has no extra effect.

How Hookdeck Can Help: A 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.

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.

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 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 for free and handle bundle.social webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.