Skip to content
Puck Docs

Subscription management

A subscription is a persistent binding between a target URL, a set of event types, and an optional filter. When a matching event fires, Puck creates a delivery for every active subscription that passes the filter. Subscriptions are per-account and isolated from other tenants.

Creating a subscription in the console

  1. Open Settings → Webhooks.
  2. Click Add subscription.
  3. Enter your endpoint URL (must be HTTPS).
  4. Select the event types you want to receive.
  5. Optionally set Minimum severity and Tag filters (see Filter knobs below).
  6. Click Create. The console displays the generated whsec_… secret exactly once — copy it now and store it securely. It will not be shown again.

Creating a subscription via the API

Terminal window
curl -X POST https://brain.your-org.example/v1/webhooks/subscriptions \
  -H "Authorization: Bearer pck_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://your-system.example/puck/events",
    "events": ["investigation.completed", "finding.discovered"],
    "filters": {
      "min_severity": "high"
    }
  }'

The response includes secret (whsec_…). Record it — this is the only time it is returned.

{
  "id":         "sub_018f2e3a…",
  "url":        "https://your-system.example/puck/events",
  "events":     ["investigation.completed", "finding.discovered"],
  "filters":    { "min_severity": "high" },
  "active":     true,
  "created_at": "2026-05-03T14:00:00Z",
  "updated_at": "2026-05-03T14:00:00Z",
  "secret":     "whsec_…"
}

Filter knobs

Filters are evaluated server-side before Puck queues a delivery. A delivery is only created if all specified filters pass.

min_severity

"filters": { "min_severity": "high" }

Accepted values: low, medium, high, critical. Events without a severity field (such as agent.registered) are always delivered regardless of this filter.

tags

"filters": {
  "tags": { "account": "prod-payments", "layer": "cloud" }
}

Every key/value pair in filters.tags must be present in the event’s tag set. Partial matches are not sufficient — all specified pairs must match. Events that carry no tags do not pass a non-empty tags filter.

Testing a subscription

The console provides a Send test event button on each subscription’s detail page (Settings → Webhooks → subscription name). This sends a synthetic investigation.queued event to your endpoint so you can verify connectivity and signature verification without waiting for a real event.

Via the API:

Terminal window
curl -X POST https://brain.your-org.example/v1/webhooks/subscriptions/sub_018f2e3a…/test \
  -H "Authorization: Bearer pck_live_…"

The test delivery appears in the delivery log under the subscription detail.

Updating a subscription

Use PATCH to update the URL, event list, filters, or active status without recreating the subscription:

Terminal window
curl -X PATCH https://brain.your-org.example/v1/webhooks/subscriptions/sub_018f2e3a… \
  -H "Authorization: Bearer pck_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["investigation.completed", "chain.confirmed"] }'

Secret rotation

To rotate the signing secret:

  1. In the console: Settings → Webhooks → subscription name → Rotate secret. The new whsec_… value is shown once.
  2. Via the API: PATCH /v1/webhooks/subscriptions/:id with "secret": "<new_secret>", or omit the field to have Puck generate one.

During rotation, update your handler to accept signatures from both the old and new secret for a short overlap window before removing the old secret. See Signature verification for the dual-validation pattern.

Disabling vs deleting

Disable ("active": false) pauses delivery without losing the subscription’s configuration, event history, or secret. The subscription remains visible in the console and the API. Use this for planned maintenance on your endpoint.

Delete (DELETE /v1/webhooks/subscriptions/:id) permanently removes the subscription. In-flight deliveries that have already been queued will still be attempted; new events will not create deliveries.

Terminal window
# Disable
curl -X PATCH https://brain.your-org.example/v1/webhooks/subscriptions/sub_018f2e3a… \
  -H "Authorization: Bearer pck_live_…" \
  -d '{ "active": false }'


# Delete
curl -X DELETE https://brain.your-org.example/v1/webhooks/subscriptions/sub_018f2e3a… \
  -H "Authorization: Bearer pck_live_…"