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 |