Webhooks
A webhook endpoint is an https address on your side. When something happens in PostSyncer, such as a post failing or an account needing a reconnect, PostSyncer sends a signed JSON request to every endpoint that listens for that event. You can manage endpoints in the app under Settings → Agents & Integrations → Webhooks (/settings/agents/webhooks), or with the API and MCP tools on these pages.
Permissions
API keys use thewebhooks permission group.
The person who owns the key must also be an owner or manager of each workspace the endpoint covers. If not, the request is refused with
403.
Rules
- The address must use
httpsand be public. Private, loopback and reserved addresses are refused, and PostSyncer checks again each time it sends. - A workspace can have 20 endpoints.
- An endpoint can listen for these events:
post.published,post.partially_published,post.failed,post.account_published,post.account_failed,post.scheduled,post.deleted,post.needs_media,approval.requested,approval.approved,approval.rejected,account.needs_reconnect,account.expires_soon,account.paused,account.connected,account.disconnected,comment.received,share.comment_received,review.received,media.generated,media.generation_failed,team.member_joined.webhook.testis sent by the test action. - By default an endpoint gets events of its own workspace. Add
account_idsto limit it to some social accounts, orworkspace_idsto also get events of other workspaces you manage.
What PostSyncer sends
webhook-id, webhook-timestamp and webhook-signature headers. See Verify webhook signatures.
id is the event’s id and is also the webhook-id header. It stays the same on every retry and on every Send again, so use it to ignore an event you already handled. timestamp is when the event happened.
data is built once, the first time the event is sent, and every retry and every Send again sends that same data. A retry hours later still tells you what happened then, not what the post looks like now. Fetch the post with Get post when you need its current state.
Events can arrive out of order. A post-level event such as post.published or post.partially_published can arrive before the last post.account_published or post.account_failed of the same post.
What data holds
Post events
post.published, post.partially_published, post.failed, post.account_published, post.account_failed, post.scheduled and post.needs_media.
data has the same fields as Get post, plus:
Each item of
accounts:
fix.code is one of reconnect, platform_hold, plan_inactive, board, media, edit, retry, not_started or support. fix.label is the button text the app shows (for example Reconnect) and fix.url opens the place in the app to fix it.
post.deleted, data is only:
post.account_* and post.needs_media keep their account_id and reason next to these.
Other events
account is always { "id", "platform", "name", "username" } and actor, the person who did it, is { "id", "name" }.
The field names of
comment and review are the ones comments and reviews use in the API. review.reviewer_name is null for an anonymous review. In an approval event post is { "id", "workspace_id", "deleted_at" } if the post was deleted first.
Delivery and retries
Answer with any2xx status within 10 seconds. A 408, 429, 5xx or a connection error is tried again after 1 minute, 10 minutes, 1 hour, 4 hours, 12 hours and 24 hours, 7 attempts in all over about 41 hours. Any other answer is not tried again. Each attempt is kept with its request and the answer, see List deliveries.
An endpoint that has been failing for 3 days is turned off, and the workspace owner is told. Turn it on again with Update webhook ("active": true).