# DunSocial webhooks: get notified when a post publishes or fails

> Set up signed DunSocial webhooks in Settings to get notified the moment a post publishes, fails, or an account needs reconnecting. No polling required.

- Published: 2026-09-25
- Last updated: 2026-09-25
- Author: Sanju (Founder & CEO @ DunSocial)
- Topics: api, how-to

---

<script>
	import { CodeSnippet } from '$lib/components/content';
</script>

The fastest way to know a scheduled post actually went out (or quietly failed) is not to keep the calendar open all day. It is a webhook: DunSocial sends your own URL a signed HTTP request the moment something happens, so a Slack channel, an internal dashboard, or a Zapier/Make/n8n flow finds out before you do.

## Short answer

Go to **Settings → Webhooks**, add an endpoint URL, name it, & pick the events you care about. DunSocial signs every delivery with HMAC-SHA256 so you can verify it really came from DunSocial, retries follow the same queue as everything else in the product, & there is a one-click **test delivery** button so you are not debugging blind on your first real event.

## What you can subscribe to

Six event types cover the whole lifecycle of a post plus one account-health signal:

| Event | Fires when |
| --- | --- |
| `post.scheduled` | A post is added to the queue |
| `post.rescheduled` | A scheduled post's time changes |
| `post.cancelled` | A scheduled post is cancelled before publish |
| `post.published` | A post goes live on the destination platform |
| `post.publish_failed` | A publish attempt fails |
| `social_account.reconnect_required` | A connected account's token needs reconnecting |

Most people start with `post.published` & `post.publish_failed`, the two that answer "did it actually go out?" without you refreshing the calendar, then add `social_account.reconnect_required` once they want to catch an expired LinkedIn or X token before it silently blocks the next week's queue.

## Set up an endpoint

1. Open **Settings → Webhooks** in your DunSocial workspace.
2. Click **Add webhook**, give it a name, & paste the URL that should receive deliveries. It must be `https://` in production; DunSocial also rejects URLs that point at a private or internal network, so this only ever reaches something on the public internet.
3. Choose which events it should receive. An endpoint that isn't subscribed to an event never gets called for it.
4. Save. DunSocial shows you the signing secret (`whsec_…`) exactly once, so copy it now. If you lose it, rotate it instead of guessing.
5. Click **Send test** to fire a sample delivery & confirm your endpoint returns a 2xx response.

Every delivery & its status (pending, success, or failed) shows up in the same Settings page, newest first, so you do not need your own logging just to see whether an endpoint is healthy.

## Verify the signature

Do not process a webhook body you cannot verify. DunSocial sends four headers with every delivery:

<CodeSnippet
	label="headers"
	lang="headers"
	code={`X-DunSocial-Event-Id: evt_...
X-DunSocial-Delivery-Id: whd_...
X-DunSocial-Timestamp: 1758825600
X-DunSocial-Signature: v1=...`}
/>

The signature is an HMAC-SHA256 of `{timestamp}.{raw request body}`, keyed with your endpoint's secret. Recompute it on your side & compare:

<CodeSnippet
	label="node"
	lang="code"
	code={`import { createHmac, timingSafeEqual } from 'node:crypto';
function isValidDunSocialWebhook(secret, timestamp, rawBody, signatureHeader) {
	const expected = 'v1=' + createHmac('sha256', secret)
		.update(timestamp + '.' + rawBody)
		.digest('hex');
	return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}`}
/>

Use the raw request body, not a re-serialized version of the parsed JSON. Most frameworks re-order or re-format keys when you stringify an object again, which breaks the comparison even though the payload is identical.

## What's in the payload

Every event shares the same envelope, with event-specific detail under `data`:

<CodeSnippet
	label="json"
	lang="code"
	code={`{
  "id": "evt_...",
  "type": "post.published",
  "apiVersion": "2026-07-06",
  "createdAt": "2026-09-25T12:00:00.000Z",
  "workspace": { "id": "...", "name": "...", "slug": "..." },
  "data": { "post": { "id": "...", "status": "published" } }
}`}
/>

`apiVersion` is a date, not a semantic version. Treat it the way you'd treat a REST API version header, & re-check the docs if you see one you don't recognize.

## Common uses

- **A Slack or Discord channel that mirrors your calendar.** Route `post.published` & `post.publish_failed` to a small relay that posts a one-line message, so a failed publish gets seen in minutes, not at your next login.
- **A custom dashboard for a client or team.** If you run DunSocial for multiple brands, a webhook-fed internal page can show live publish status without your own team polling the API.
- **Zapier, Make, or n8n.** Point the webhook at that tool's inbound-webhook trigger & branch on `type` from there. No DunSocial-specific connector required, since it's a standard signed HTTP POST.
- **Catching a dead connection early.** `social_account.reconnect_required` fires before a whole week of scheduled posts quietly fails on an expired token, instead of after.

Webhooks pair well with the [REST API](/blog/schedule-posts-with-the-dunsocial-api) & the [CLI](/blog/post-and-schedule-from-the-terminal-with-the-dunsocial-cli): schedule programmatically, then get told what happened without polling for it.

## Pricing & availability

Webhooks are included in DunSocial's **$20/mo** or **$192/yr** plan, with no separate developer add-on, no per-delivery fee. 14-day trial, no card. One seat included; extra seats are $8/mo. Full API & webhook reference: [dunsocial.com/docs/api](https://www.dunsocial.com/docs/api) and [dunsocial.com/docs/api/webhooks](https://www.dunsocial.com/docs/api/webhooks).

## FAQ

### Do webhooks cost extra?

No. Webhooks are part of the same $20/mo or $192/yr plan as everything else, with no separate API or automation add-on.

### How many webhook endpoints can I add?

You can add more than one endpoint & subscribe each to a different subset of events. That's useful if, say, a Slack relay only needs `post.publish_failed` while an internal dashboard wants everything.

### What happens if my endpoint is down?

A failed delivery shows as `failed` in the Settings delivery log with the response DunSocial received (or the timeout), so you can see exactly why without guessing. Re-run **Send test** once your endpoint is back up to confirm it recovers.

### Can I use webhooks without also using the API or CLI?

Yes. Webhooks work independently: you can schedule everything from the DunSocial web app and still get notified by webhook when those posts publish or fail. The API and CLI are for scheduling programmatically; webhooks are for finding out what happened.

### Is the payload the same for every event type?

The envelope (`id`, `type`, `apiVersion`, `createdAt`, `workspace`) is identical across all six event types; only the shape of `data` changes per event. Check [the webhooks docs](https://www.dunsocial.com/docs/api/webhooks) for each event's exact `data` shape.

---

## About this document

This is the Markdown representation of https://www.dunsocial.com/blog/dunsocial-webhooks-get-notified-when-a-post-publishes-or-fails. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login