Webhooks API
Configure and manage webhooks for real-time event notifications.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /webhooks | List webhook endpoints |
POST | /webhooks | Create a webhook |
GET | /webhooks/:id | Get webhook details |
PATCH | /webhooks/:id | Update a webhook |
DELETE | /webhooks/:id | Delete a webhook |
GET | /webhooks/:id/deliveries | List delivery attempts |
POST | /webhooks/:id/test | Send test event |
Webhook Object
Loading code block...
Available Events
Project Events
| Event | Description |
|---|---|
project.created | New project created |
project.updated | Project settings updated |
project.deleted | Project deleted |
Agent Events
| Event | Description |
|---|---|
agent.invoked | Agent was invoked |
agent.completed | Agent completed task |
agent.failed | Agent invocation failed |
Skill Events
| Event | Description |
|---|---|
skill.applied | Skill pattern applied |
skill.failed | Skill application failed |
Usage Events
| Event | Description |
|---|---|
usage.threshold_reached | Usage threshold reached |
usage.limit_exceeded | Usage limit exceeded |
Subscription Events
| Event | Description |
|---|---|
subscription.created | Subscription started |
subscription.updated | Subscription changed |
subscription.canceled | Subscription canceled |
invoice.paid | Invoice payment succeeded |
invoice.payment_failed | Invoice payment failed |
List Webhooks
Loading code block...
Example Request
Loading code block...
Response
Loading code block...
Create Webhook
Loading code block...
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS endpoint URL |
events | array | Yes | Events to subscribe to |
metadata | object | No | Custom metadata |
Example Request
Loading code block...
Response
Loading code block...
Important: The secret is only shown once. Store it securely for signature verification.
Update Webhook
Loading code block...
Request Body
| Field | Type | Description |
|---|---|---|
url | string | Endpoint URL |
events | array | Events to subscribe to |
status | string | active or disabled |
metadata | object | Custom metadata |
Example Request
Loading code block...
Delete Webhook
Loading code block...
Example Request
Loading code block...
List Deliveries
Loading code block...
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter: success, failed, pending |
limit | integer | Number of deliveries (default: 20) |
Response
Loading code block...
Send Test Event
Loading code block...
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
event | string | Yes | Event type to simulate |
Example Request
Loading code block...
Webhook Payload Format
Headers
Loading code block...
Body
Loading code block...
Signature Verification
Verify webhook signatures to ensure requests are from Bootspring.
Node.js
Loading code block...
Python
Loading code block...
Retry Policy
Failed deliveries are retried with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 12 hours |
| 7 | 24 hours |
After 7 failed attempts, the delivery is marked as failed.
Best Practices
1. Respond Quickly
Return a 2xx response within 30 seconds:
Loading code block...
2. Handle Duplicates
Webhooks may be delivered multiple times. Use the event id for idempotency:
Loading code block...
3. Verify Signatures
Always verify signatures in production.
4. Use HTTPS
Webhook endpoints must use HTTPS.
Webhook Limits
| Plan | Webhooks | Events/Hour |
|---|---|---|
| Free | 1 | 100 |
| Pro | 5 | 1,000 |
| Team | 20 | 10,000 |
| Enterprise | Unlimited | Unlimited |
Errors
| Code | Description |
|---|---|
webhook_not_found | Webhook doesn't exist |
webhook_limit_exceeded | Maximum webhooks reached |
invalid_url | URL is not valid HTTPS |
invalid_event | Unknown event type |