Overview

Webhooks push a JSON payload to a URL you control whenever a subscribed event happens. They replace polling for anything that is not immediate.

When to use webhooks

• You need to react to a published post (for example, cross-post to a network we do not natively support).
• You want to write successful campaign launches into your CRM.
• You want to keep your CMS in sync when content is deleted.
• You want a Slack notification the moment a Meta OAuth connection breaks.

Delivery guarantees

• At-least-once. The same event may arrive twice if your endpoint is slow to acknowledge. Idempotency is on you.
• Payload is not ordered. Two events fired 50 ms apart may arrive in either order. Use the event_id and per-payload timestamps to reconcile.
• Deliveries time out at 10 seconds. Return 2xx fast, then process asynchronously if needed.

Delivery envelope

Every event has the same envelope:

{
  "id": "evt_9c2b1a3f4d5e6708",
  "type": "content.published",
  "workspace_id": "org_2gK9c7dL3eX8fY1a",
  "created_at": "2026-07-19T13:00:04Z",
  "data": { /* event-specific payload */ }
}

data shape depends on type. See Events for the catalog.

Headers

Every delivery includes:

Header	Meaning
Nativpost-Signature	HMAC-SHA256 signature, see Signature verification.
Nativpost-Event	The event type, mirrored from the body for cheap routing.
Nativpost-Delivery	A unique id for this delivery attempt. Useful for support tickets.
Content-Type	application/json.

First-time setup

1. Create a subscription via POST /webhooks and record the plaintext signing_secret.
2. Point it at an endpoint that returns 200 for any body.
3. Fire a test delivery with POST /webhooks/{id}/test and confirm your logs.
4. Enable signature verification before you start acting on data.

What happens when your endpoint fails

If NativPost sees five failed deliveries in a row over one hour, the subscription is auto-disabled. is_enabled stays false and auto_disabled_at is set. Re-enable via PATCH /webhooks/{id} once you have fixed the endpoint. See Retries and delivery log for the retry schedule.