Webhooks

Manage outbound webhook subscriptions for your workspace.

Endpoints

Method	Path	Description	Required Scopes
GET	/v1/webhooks/subscriptions	List webhook subscriptions for the current workspace.	webhooks:read
POST	/v1/webhooks/subscriptions	Create a webhook subscription and generate a secret.	webhooks:write
GET	/v1/webhooks/subscriptions/:id	Fetch a single subscription by ID.	webhooks:read
PATCH	/v1/webhooks/subscriptions/:id	Update subscription metadata, events, or status.	webhooks:write
DELETE	/v1/webhooks/subscriptions/:id	Delete a subscription.	webhooks:delete or webhooks:write
POST	/v1/webhooks/subscriptions/:id/rotate-secret	Rotate the shared secret and reset retry counters.	webhooks:write

All requests require workspace context via your API key. You can also manage webhooks from the Voyant dashboard.

Key concepts

• Events: Provide one or more event keys. Wildcards are supported (product.*, *).
• Secrets: A 64-character hex secret is generated on creation and rotation. The secret is only returned once—store it securely.
• Headers: Optional key/value pairs for custom authentication headers sent with each delivery.
• Retries: max_retries controls exponential backoff attempts (0–10, default 5). Failures increment failure_count for monitoring.
• Active: Set active: false to pause deliveries without deleting the subscription.