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.

Verifying The Signature

The header is t=<unix_seconds>,v1=<hex>, where v1 is HMAC-SHA256(signing_secret, "<t>.<raw_request_body>"). Compute it over the raw body, before any JSON parsing or re-serialization, and compare with a constant-time equality check.

Each workspace has its own signing secret. Fetch it with an API key holding the api_keys.write scope:

curl -s "$POSTMCP_API_URL/workspaces/$POSTMCP_WORKSPACE_ID/webhook-signing-secret" \
  -H "Authorization: Bearer $POSTMCP_API_KEY"

{
  "workspace_id": "wrk_...",
  "signing_secret": "...",
  "signature_header": "x-postmcp-signature",
  "signed_payload_format": "{timestamp}.{raw_request_body}",
  "algorithm": "HMAC-SHA256"
}

Store it as a secret on your receiver. It is specific to your workspace, so it cannot be used to sign deliveries for anyone else — and no other workspace's secret can be used to sign yours.

Also reject deliveries whose t is far from your own clock (five minutes is a reasonable window), so a captured payload cannot be replayed indefinitely.

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.