Webhook Delivery

PostMCP can send post lifecycle events to an agent-controlled HTTPS endpoint when a post write includes webhook_url.

Request Field

Add webhook_url to post creation, scheduling, batch, or retry requests:

{
  "workspace_id": "wrk_123",
  "text": "Launch note",
  "scheduled_at": "2026-05-15T14:00:00.000Z",
  "webhook_url": "https://example.com/postmcp/webhooks",
  "targets": [{ "platform": "bluesky", "connected_account_id": "acct_123" }]
}

CLI users can pass the same value with --webhook-url.

Delivery Headers

Webhook receivers should verify and log these headers:

x-postmcp-event
x-postmcp-delivery-id
x-postmcp-signature

Events include post.scheduled, post.published, post.failed, and related post lifecycle outcomes. Use x-postmcp-event to route the event and preserve the delivery ID in logs.

Security

Use public HTTPS endpoints only. PostMCP rejects unsafe webhook destinations such as localhost, private network addresses, and non-HTTPS URLs.

Verify x-postmcp-signature before trusting the payload. Treat failed signature verification as an authentication failure and return a non-2xx status.

Retries And Dead Letters

Webhook delivery retries transient failures on the documented retry schedule. After retries are exhausted, the delivery is marked dead-letter so operators can inspect or replay it later.

Sandbox webhook deliveries are retained for a shorter period than production deliveries. For agent workflows, always record the event, delivery ID, post group ID, and trace_id if the payload includes one.