---
title: "Post events"
method: POST
path: "postEvents"
tags: ["Webhook Events"]
---

# Post events

`POST postEvents` (webhook)

- `post.scheduled`: A post became scheduled or its scheduled time changed, including moves by a queue reshuffle; content-only edits, drafts, and posts published immediately do not emit it.
- `post.published`: Every target of a post published successfully.
- `post.partially_failed`: A post finished publishing with at least one target published and the rest failed or canceled.
- `post.failed`: A post finished publishing and none of its targets published.
- `post.cancelled`: A scheduled or queued post was deleted (`reason: deleted`) or moved back to a draft (`reason: unscheduled`) before it published.

Delivered as a `POST` to every active endpoint that subscribes to the event and whose profile access covers it. Delivery is at least once and events are not ordered, so deduplicate by `id`.

## Payload

- WebhookPostEvent: Envelope for `post.scheduled`, `post.published`, `post.partially_failed`, `post.failed`, `post.cancelled`.
  - `id` string, required: Event id (`evt_…`). Stable across automatic retries and manual redeliveries; deduplicate on it.
  - `type` 'post.scheduled' | 'post.published' | 'post.partially_failed' | 'post.failed' | 'post.cancelled', required
  - `apiVersion` string, required: Payload version.
  - `createdAt` string, date-time, required: When the event was created.
  - `data` WebhookPostEventData, required
    - `post` WebhookPostEventPost, required
      - `id` string, required: PostZen post id.
      - `profileId` string, required: The post's primary profile.
      - `status` 'scheduled' | 'published' | 'partially_failed' | 'failed' | 'canceled', required: `scheduled` for post.scheduled, `canceled` for post.cancelled, otherwise the final publish outcome.
      - `scheduledFor` string, date-time, nullable, required: Scheduled publish time, or null for a post that was published immediately. For post.cancelled, the time the post was scheduled for.
      - `targets` WebhookPostEventTarget[], required
        - `accountId` string, required: PostZen account id.
        - `profileId` string, required: The target account's profile. A post's targets can span profiles.
        - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram', required: Platform of the account an event refers to. Webhook payloads use `x` for X (Twitter).
        - `status` 'draft' | 'scheduled' | 'queued' | 'publishing' | 'published' | 'partially_failed' | 'failed' | 'canceled', required: Status of one platform target when the event was created.
        - `platformPostUrl` string, uri: Public URL of the published post, when the platform returned one.
        - `errorCode` string: Present when the target failed.
      - `reason` 'deleted' | 'unscheduled': post.cancelled only. `deleted` when the post was deleted, `unscheduled` when it was moved back to a draft.

## Acknowledgement `2XX`

Acknowledges the delivery. Any other status, or no response within 10 seconds, schedules a retry.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)