Skip to main content

​
Webhook lifecycle

  1. Create an org-scoped webhook endpoint with POST /v1/webhook_endpoints
  2. Store the returned signingSecret at creation time or after a secret rotation
  3. Verify inbound signatures using the raw request body plus x-secapi-signature-timestamp
  4. Use POST /v1/webhook_endpoints/{webhook_id}/rotate_secret when a secret is exposed or stale
  5. Inspect recent attempts with GET /v1/webhook_endpoints/{webhook_id}/deliveries
  6. Replay a failed attempt with POST /v1/webhook_endpoints/{webhook_id}/deliveries/{delivery_id}/replay

​
Stream lifecycle

  1. Create a stream subscription with POST /v1/stream_subscriptions
  2. Subscribe to the smallest event set that supports the workflow
  3. Track the returned cursor and lastEventAt fields for replay and polling
  4. Use GET /v1/delivery/events for cross-surface delivery history and GET /v1/stream_subscriptions/{stream_id}/events for subscription-specific polling

​
Event types

Use GET /v1/event_types?status=public_emitting as the source of truth for event names, producer status, replay support, retention, and billing family. Reserved event types are intentionally excluded from this public filter until their producers are shipping.

​
Example CLI usage

secapi webhooks create \
  --destination-url https://example.com/hooks/secapi \
  --event-types artifact.created,artifact.reconciled

secapi streams create \
  --event-types artifact.created,artifact.reconciled \
  --transport poll

secapi webhooks rotate-secret --webhook-id wh_123
Webhook and stream delivery units are billed through delivery_events. Customer monitor email notifications are billed through the separate email_notifications meter.