# How to set up a DunSocial webhook endpoint

> Add an endpoint under Settings → Webhooks, or POST /api/webhooks with a session token. Pick the events you want, save the secret it shows once, then send a test delivery. Only workspace owners & admins can manage endpoints, & PATs can't.

Updated: 2026-10-05.

## What webhooks are for

A webhook tells your own system when something happens, so you don't have to poll. The common uses are logging published posts, alerting on failures & triggering follow-up work.

## The events

- `post.scheduled`
- `post.rescheduled`
- `post.cancelled`
- `post.published`
- `post.publish_failed`
- `social_account.reconnect_required`

Subscribe to only what you need. `post.publish_failed` & `social_account.reconnect_required` are the two most useful for alerting.

## Option 1: in the app

Open Settings → Webhooks & add an endpoint. Enter a name & the URL that should receive events, choose which events to send & save. Make sure the endpoint is enabled.

## Option 2: through the API

Endpoint management needs a session bearer token & the workspace header, since PATs can't manage webhooks. The signed-in member must be an owner or admin:

```bash
curl -X POST https://api.dunsocial.com/api/webhooks \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production hooks",
    "url": "https://example.com/hooks/dunsocial",
    "events": ["post.published", "post.publish_failed"],
    "enabled": true
  }'
```

It returns 201 with the endpoint & a plain `secret`, once.

## Store the secret now

The secret is returned only when you create or rotate an endpoint, & the current one can't be revealed later. Put it in your secret manager straight away.

If you lose it, rotate it with `POST /api/webhooks/:id/rotate-secret` & update your receiver.

DunSocial never shows the current secret again, which is why rotation exists.

## Test it

`POST /api/webhooks/:id/test` sends a test delivery to your URL. Use it to confirm your receiver is reachable & your signature check works before real events arrive.

A workspace can have up to 10 endpoints, so use separate ones for separate systems.

DunSocial's test delivery goes to the URL you registered, so it exercises your receiver end to end.

## Watch deliveries

`GET /api/webhooks/:id/deliveries` returns a paginated log you can filter by status or event type. Each entry shows the event, the delivery status, the number of attempts & the last response code or error.

DunSocial retries a failed delivery a few times, & the log is where you see why one failed. Your endpoint should return a success response quickly & do slow work afterwards.

## Manage endpoints

You can list, get, update & delete endpoints. List responses mask the secret, & delete is a soft delete.

DunSocial's team roles apply here: only owners & admins can change webhooks, so a member can't quietly redirect events elsewhere.

## Related guides

- [How to verify a DunSocial webhook signature](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-verify-a-dunsocial-webhook-signature.md)
- [What are webhooks for social media posting?](https://www.dunsocial.com/hub/social-media-automation-for-developers/what-are-webhooks-for-social-media-posting.md)
- [What happens if a scheduled post fails?](https://www.dunsocial.com/hub/social-media-scheduler/what-happens-if-a-scheduled-post-fails.md)
- [How to authenticate with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-authenticate-with-the-dunsocial-api.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-set-up-a-dunsocial-webhook-endpoint. 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