Webhooks are how you know if a post actually went live or if it exploded. Instead of polling us every 2 seconds like a psychopath, just give us a URL and we’ll tell you.
Prerequisite: You need an API Key and a URL where we can send POST requests. Webhooks are configured at the organization level - all teams under that org share the same webhook endpoints.
Setup
- Go to the Webhooks Dashboard.
- Add your URL (e.g.,
https://api.yourapp.com/webhooks/bundle). Must be HTTPS.
- Get your Signing Secret.
Local Dev: Use ngrok to test locally. ngrok http 3000.
Events
| Event | When it fires |
|---|
post.published | Post went live (or failed permanently after retries) |
post.failed | Post failed - check the error details |
comment.published | First comment was posted (or failed permanently) |
social-account.created | User connected a new social account |
social-account.updated | Social account changed (channel unset, remote disconnection detected) |
social-account.deleted | Social account was disconnected or removed |
team.created | A new team was created |
team.updated | Team details changed (name, avatar, social accounts added/removed) |
team.deleted | A team was deleted |
team.updated also fires when a social account is added to or removed from a team - so you don’t need to listen to social account events separately if you’re already tracking teams.
Payload Structure
Every webhook delivery is an HTTP POST with this shape:
{
"type": "post.published",
"data": {
// ... event-specific payload
}
}
| Header | Value |
|---|
Content-Type | application/json |
User-Agent | bundlesocial |
x-signature | HMAC-SHA256 signature (see Security) |
Post Events Payload
When you receive post.published or post.failed, the data field contains the full post object:
{
"type": "post.published",
"data": {
"id": "post_abc123",
"title": "My awesome post",
"content": "Hello world!",
"status": "POSTED",
"scheduledDate": "2026-01-15T10:00:00.000Z",
"postedDate": "2026-01-15T10:00:02.341Z",
"teamId": "team_xyz",
"createdAt": "2026-01-14T15:30:00.000Z",
"updatedAt": "2026-01-15T10:00:02.341Z",
"deletedAt": null,
"uploads": [
{
"upload": {
"id": "upload_456",
"fileName": "cover.jpg",
"mimeType": "image/jpeg",
"size": 245000
}
}
],
"socialAccounts": [
{
"socialAccount": {
"id": "sa_789",
"type": "INSTAGRAM",
"username": "mybrand",
"displayName": "My Brand"
}
}
]
}
}
{
"type": "comment.published",
"data": {
"id": "comment_abc",
"content": "#growth #mindset",
"status": "POSTED",
"postId": "post_abc123",
"teamId": "team_xyz",
"createdAt": "2026-01-15T10:00:05.000Z",
"socialAccounts": [
{
"socialAccount": {
"id": "sa_789",
"type": "INSTAGRAM",
"username": "mybrand"
}
}
]
}
}
Social Account Events Payload
{
"type": "social-account.created",
"data": {
"id": "sa_789",
"type": "INSTAGRAM",
"teamId": "team_xyz",
"username": "mybrand",
"displayName": "My Brand",
"avatarUrl": "https://...",
"externalId": "17841400000",
"channels": [],
"createdAt": "2026-01-10T12:00:00.000Z"
}
}
accessToken, refreshToken, secret, and expiresAt are never included in webhook payloads. We’re not that reckless.
Team Events Payload
{
"type": "team.created",
"data": {
"id": "team_xyz",
"name": "Marketing Team",
"avatarUrl": "https://...",
"organizationId": "org_123",
"createdById": "user_456",
"createdAt": "2026-01-10T12:00:00.000Z",
"organization": { "id": "org_123", "name": "Acme Corp" },
"createdBy": { "id": "user_456", "email": "..." },
"socialAccounts": []
}
}
Delivery & Retries
We really try to deliver your webhooks. Here’s how hard we try:
| Setting | Value |
|---|
| Timeout | 15 seconds per request |
| Max attempts | 3 (initial + 2 retries) |
| Backoff | Exponential, starting at 30 seconds |
| Concurrency | We process up to 50 deliveries simultaneously |
Auto-Disable (The Safety Net)
If your webhook endpoint fails 50 consecutive times within a 24-hour window, we automatically disable it. This protects both of us - we stop wasting resources, and you stop missing events you don’t know about.
When this happens:
- Your webhook is marked as disabled
- We stop sending events to that URL
- You can re-enable it from the dashboard or API (this resets the failure counter)
- On the next successful delivery, the failure counter resets to 0
Don’t let your endpoint go down for too long. 50 consecutive failures is generous, but if your server is having a bad day, re-enable manually once it’s back. Events that happened while disabled are gone - we don’t replay them.
Resending Events
Made a mistake in your handler? Event got lost? You can resend any webhook event from the dashboard or via the API. We’ll create a fresh delivery attempt with the same payload.
Remote Disconnection Detection
We check every connected social account every 6 hours to see if it’s still valid. If the platform tells us “nope, this token is dead,” we start the disconnection flow.
How It Works
- Every 6 hours, we validate each connected account against its platform.
- If the check fails, we retry 3 times with 10-minute backoff.
- If all retries fail, we schedule the account for deletion and send you a
social-account.updated webhook.
- After the grace period, we remove the account (fires
social-account.deleted).
This covers all OAuth-connected platforms - Meta (Facebook, Instagram, Threads), YouTube, TikTok, Twitter, LinkedIn, Pinterest, Reddit, Discord, Slack, Mastodon, Bluesky, and Google Business.
The social-account.updated Payload
When we detect a disconnection, the webhook includes a socialAction object with the details:
{
"type": "social-account.updated",
"data": {
"id": "sa_789",
"type": "INSTAGRAM",
"teamId": "team_xyz",
"username": "mybrand",
"socialAction": {
"type": "disconnect-check",
"source": "system",
"checkedAt": "2026-02-20T14:30:00.000Z",
"details": {
"status": "error",
"code": "REMOTE_DISCONNECT_DELETION_SCHEDULED",
"message": "Account failed validation after 3 attempts",
"attemptNumber": 3,
"attemptsTotal": 3,
"scheduledForDeletion": true,
"deleteAccountAfter": 6,
"deleteOn": "2026-02-20T20:30:00.000Z"
}
}
}
}
Status Codes
| Code | Meaning |
|---|
REMOTE_DISCONNECT_DELETION_SCHEDULED | All retries failed. Account is scheduled for deletion. |
REMOTE_DISCONNECT_UNAUTHORIZED_WARNING | Token refresh failed with an auth error (401, expired token, etc.). |
REMOTE_DISCONNECT_REAUTH_REQUIRED | Connection failed for another reason. User should reconnect. |
The deleteOn Grace Period
When an account is scheduled for deletion, deleteOn tells you exactly when it will be removed. The delay is controlled by deleteAccountAfter on your organization settings (0–24 hours).
- Default: 0 hours - account is removed almost immediately.
- If you set it to e.g. 6 hours - you get a 6-hour window to notify your user before the account is gone.
Why does this matter? When an account is deleted:
- It’s removed from all draft and scheduled posts.
- Posts that only had this account become drafts.
- If the user reconnects before
deleteOn, the account stays.
Best Practices
- Respond fast. Return a
200 within 15 seconds. Do heavy processing asynchronously. If you take too long, we’ll count it as a failure.
- Be idempotent. We might deliver the same event twice in rare cases (retries, race conditions). Use the event ID to deduplicate.
- Verify signatures. Always. No exceptions. Even in development. See the SDK for built-in signature verification, or check the Swagger for the raw details.
- Use HTTPS. We only send webhooks to HTTPS URLs. Sorry,
http://localhost works via ngrok though.
- Monitor your failures. If you’re getting close to 50 consecutive failures, fix your endpoint before we disable it.
