Webhooks

Capability and Access

Webhook routes are tenant/workspace scoped and require:

• Professional subscription tier or above.
• Webhook permissions (webhooks:read, webhooks:create, etc.).

Management Endpoints

• GET /webhooks list subscriptions.
• POST /webhooks create subscription.
• PUT /webhooks/{webhook_id} update subscription.
• DELETE /webhooks/{webhook_id} remove subscription.
• POST /webhooks/{webhook_id}/test send test event.
• GET /webhooks/{webhook_id}/deliveries inspect delivery history.

Create Payload Essentials

Typical create fields:

• url
• events (event types to subscribe)
• secret (for signature verification)
• is_active

Delivery Monitoring

Use delivery history endpoint to track:

• status code and success/failure
• retry attempts
• response latency
• error details

Current Test Endpoint Behavior

The test endpoint currently returns a successful test response and is marked for deeper delivery implementation.

Treat it as a configuration smoke check, not a full delivery guarantee.

Operational Best Practices

• Use dedicated endpoint URLs per environment.
• Rotate webhook secrets on a schedule.
• Alert on sustained delivery failures.
• Replay or retry failed events through operational runbook procedures.