Webhook post events

Before you start

You need an API key and a connected LinkedIn account: account_ids is required and non-empty, and a post webhook can never cover every account. Read your ids with GET /v1/accounts; if it is empty, start with the Quickstart.

Quick reference

Event	Availability	Description
`post.published`	Real-time	A scheduled post was published.
`post.publish_failed`	Real-time	A scheduled post could not be published.

Both events are default-subscribed: omit events and the webhook receives both.

curl -X POST https://api.curviate.com/v1/webhooks \
  -H "Authorization: Bearer cvt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "post",
    "request_url": "https://hooks.example.com/curviate",
    "account_ids": ["acc_YOUR_ACCOUNT_ID"]
  }'

Only scheduled posts emit these events

The events fire when a scheduled draft reaches its time. Publishing right away and POST /v1/posts never emit them: those calls return the result directly.

`post.published`

Fired when a scheduled post went live.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "post.published",
  "data": {
    "draft_id":     "drf_YOUR_DRAFT_ID",
    "post_id":      "post_YOUR_POST_ID",
    "account_id":   "acc_YOUR_ACCOUNT_ID",
    "scheduled_at": "2026-10-07T08:00:00.000Z",
    "published_at": "2026-10-07T08:00:04.000Z"
  },
  "delivered_at": "2026-10-07T08:00:05.100Z"
}

Notable fields

data.post_id: the published post's id, or null when none was returned. A null does not mean the post failed.
data.scheduled_at: the time you scheduled. published_at is when it went live.
data.safety_warning: present only when the publish went out in breach of a safety limit you set to warn instead of block (a daily budget or an activity window). Absent otherwise.

`post.publish_failed`

Fired when a scheduled post could not be published.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "post.publish_failed",
  "data": {
    "draft_id":        "drf_YOUR_DRAFT_ID",
    "account_id":      "acc_YOUR_ACCOUNT_ID",
    "scheduled_at":    "2026-10-07T08:00:00.000Z",
    "failure_code":    "rate_limited",
    "failure_message": "The account hit a platform rate limit."
  },
  "delivered_at": "2026-10-07T08:00:02.400Z"
}

failure_message is a short description of the cause, never the post text.

Failure codes

Code	Meaning
`platform_error`	The platform returned an error.
`rate_limited`	The platform rate-limited the account.
`account_unavailable`	The account could not act (disconnected or needs reconnecting).
`media_rejected`	The platform rejected the attached media.
`budget_exhausted`	The account's daily action budget was used up.
`outside_activity_window`	The scheduled time fell outside the account's activity window.
`no_active_seat`	The account had no active seat at fire time.
`not_publishable`	The draft was not in a publishable state.
`platform_rejected`	The platform rejected the post.
`missed`	The scheduled time passed without a publish attempt.
`outcome_unknown`	The publish call timed out or ended without a usable answer after the request was sent.

outcome_unknown: the post may be live

The request was sent but no usable answer came back. Check the account's posts before retrying, or you may publish it twice.

Field remapping

The post source has no data remap keys. The payloads above are fixed.

Errors you may hit

Code	HTTP	Cause	Fix
`INVALID_REQUEST`	400	`account_ids` omitted, empty, or `null` (a `post` webhook is per-account), or an event that does not belong to the `post` source.	Send a non-empty `account_ids`; the `message` names the accepted events.
`ACCOUNT_NOT_FOUND`	404	An `acc_...` in `account_ids` is not owned by this tenant.	Read your ids from `GET /v1/accounts`.
`UNAUTHORIZED`	401	Missing or invalid API key.	Send `Authorization: Bearer cvt_live_<key>`.
`PAYMENT_REQUIRED`	402	No active subscription.	Add a seat in the dashboard.
`RATE_LIMIT_TENANT`	429	Tenant quota exceeded.	Honour the `Retry-After` header.

Full envelope shapes are in the error reference.

Next steps

Verifying signatures: validate every delivery before you process it.
Delivery and retries: the retry schedule and endpoint health.
Event reference: every event, by source.

Post events