Webhooks

Webhook subscriptions let your systems react to workspace events without polling. Every subscription has a URL, a subscribed event list, and a signing secret.

For a conceptual overview see Webhooks: Overview. This page documents the CRUD endpoints.

List

GET /api/v1/webhooks

{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "whk_1f2e3d4c5b6a",
      "url": "https://example.com/hooks/nativpost",
      "events": ["content.published", "content.publish_failed"],
      "is_enabled": true,
      "auto_disabled_at": null,
      "created_at": "2026-07-10T09:00:00Z"
    }
  ],
  "has_more": false
}

Retrieve

GET /api/v1/webhooks/{id}

Create

POST /api/v1/webhooks

curl -X POST https://app.nativpost.com/api/v1/webhooks \
  -H "Authorization: Bearer $NATIVPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/nativpost",
    "events": ["content.published", "campaign.launched"]
  }'

The response includes the signing secret exactly once:

{
  "object": "webhook",
  "id": "whk_1f2e3d4c5b6a",
  "url": "https://example.com/hooks/nativpost",
  "events": ["content.published", "campaign.launched"],
  "signing_secret": "whsec_a1b2c3d4e5f6...",
  "is_enabled": true
}

Store the secret in your secrets manager immediately. Later GET responses replace it with signing_secret: null.

Update

PATCH /api/v1/webhooks/{id}

Editable fields: url, events, is_enabled.

Rotate the secret

POST /api/v1/webhooks/{id}/rotate

Generates a fresh signing secret and invalidates the previous one. Returns the same shape as create.

Send a test event

POST /api/v1/webhooks/{id}/test

Delivers a synthetic webhook.test event to the endpoint. Response contains the delivery outcome:

{
  "delivered": true,
  "status_code": 200,
  "duration_ms": 142
}

Delivery log

GET /api/v1/webhooks/{id}/deliveries?limit=25

Returns the most recent attempts with per-attempt status codes, response bodies (truncated to 8 KB), and durations. Useful for debugging endpoints that reject events.

Delete

DELETE /api/v1/webhooks/{id}