Skip to main content

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 the webhooks 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 https and 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.test is sent by the test action.
  • By default an endpoint gets events of its own workspace. Add account_ids to limit it to some social accounts, or workspace_ids to also get events of other workspaces you manage.

What PostSyncer sends

Every request carries 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.
(The Get post fields are shortened here.) If the post was deleted before the event was first sent, and always for 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 any 2xx 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).

Endpoints