> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsyncer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get PostSyncer events as signed JSON requests at your own address

## 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.

| Permission | Allows |
| - | - |
| `webhooks:read` | List and get endpoints, list deliveries |
| `webhooks:create` | Create endpoints |
| `webhooks:update` | Edit endpoints and send test events |
| `webhooks:delete` | Delete endpoints |

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

```json theme={null}
{
  "type": "post.failed",
  "id": "01JC8Z4Q2M7H3V9K5R6T1N0XWD",
  "timestamp": "2026-11-15T09:12:44+00:00",
  "workspace_id": 12,
  "data": { }
}
```

Every request carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers. See [Verify webhook signatures](https://docs.postsyncer.com/guides/verify-webhooks.md).

`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](https://docs.postsyncer.com/api-reference/posts/get.md) 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](https://docs.postsyncer.com/api-reference/posts/get.md), plus:

| Field | Type | Description |
| - | - | - |
| `accounts` | array | Each account's result when the event happened, failed ones first. See below. |
| `account_id` | integer | `post.account_published` and `post.account_failed` only: the account this event is about. |
| `reason` | string or null | `post.needs_media` only: why the media couldn't be made. |

Each item of `accounts`:

| Field | Type | Description |
| - | - | - |
| `account_id` | integer | The social account's id |
| `platform` | string | `twitter`, `instagram`, `linkedin` and so on |
| `name` | string or null | The account's display name |
| `username` | string or null | The account's handle |
| `status` | string | The account's result, such as `PUBLISHED` or `FAILED` |
| `post_url` | string or null | The live post's address, once published |
| `error` | string or null | What the platform said, for a failed account |
| `fix` | object or null | What to do about a failed account: `code`, `label` and `url`. `null` when there is nothing to do. |

`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.

```json theme={null}
{
  "id": 4821,
  "status": "PARTIALLY_FAILED",
  "content": "Fresh batch is in",
  "accounts": [
    {
      "account_id": 77,
      "platform": "instagram",
      "name": "Kestrel",
      "username": "kestrel",
      "status": "FAILED",
      "post_url": null,
      "error": "Instagram says the video is too long.",
      "fix": { "code": "media", "label": "Change media", "url": "https://app.postsyncer.com/..." }
    },
    {
      "account_id": 78,
      "platform": "linkedin",
      "name": "Kestrel Co",
      "username": "kestrelco",
      "status": "PUBLISHED",
      "post_url": "https://www.linkedin.com/feed/update/...",
      "error": null,
      "fix": null
    }
  ]
}
```

(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:

```json theme={null}
{ "id": 4821, "workspace_id": 12, "deleted_at": "2026-11-15T09:12:44+00:00" }
```

`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" }`.

| Event | `data` |
| - | - |
| `approval.requested` | `post` (same fields as [Get post](https://docs.postsyncer.com/api-reference/posts/get.md)), `actor` |
| `approval.approved` | `post`, `actor` |
| `approval.rejected` | `post`, `actor`, `reason` (string or null) |
| `account.needs_reconnect` | `account`, `reason` (string or null) |
| `account.expires_soon` | `account`, `days` (integer), `expires_at` (ISO 8601) |
| `account.paused` | `account` |
| `account.connected` | `account`, `actor` |
| `account.disconnected` | `account`, `actor` |
| `comment.received` | `post` (`{ "id", "workspace_id" }`), `account`, `comment` (`{ "author_name", "content" }`) |
| `share.comment_received` | `post` (`{ "id", "workspace_id" }`), `comment` (`{ "author_name", "content" }`) |
| `review.received` | `account`, `review` (`{ "reviewer_name", "star_rating", "comment" }`) |
| `media.generated` | `media` (`{ "kind": "image" or "video", "title", "error": null }`) |
| `media.generation_failed` | `media` (`{ "kind", "title", "error" }`) |
| `team.member_joined` | `member` (`{ "name", "role" }`) |
| `webhook.test` | `message` |

The field names of `comment` and `review` are the ones [comments](https://docs.postsyncer.com/api-reference/comments/list.md) 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](https://docs.postsyncer.com/api-reference/webhooks/deliveries.md).

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](https://docs.postsyncer.com/api-reference/webhooks/update.md) (`"active": true`).

### Endpoints

* [List webhooks](https://docs.postsyncer.com/api-reference/webhooks/list.md)
* [Create webhook](https://docs.postsyncer.com/api-reference/webhooks/create.md)
* [Update webhook](https://docs.postsyncer.com/api-reference/webhooks/update.md)
* [Delete webhook](https://docs.postsyncer.com/api-reference/webhooks/delete.md)
* [Test webhook](https://docs.postsyncer.com/api-reference/webhooks/test.md)
* [List deliveries](https://docs.postsyncer.com/api-reference/webhooks/deliveries.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.