Webhooks API | Bootspring Docs

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#

{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/bootspring",
  "events": ["project.created", "agent.invoked"],
  "status": "active",
  "secret": "whsec_xxx...",
  "metadata": {
    "environment": "production"
  },
  "stats": {
    "deliveriesTotal": 156,
    "deliveriesSucceeded": 152,
    "deliveriesFailed": 4,
    "lastDeliveryAt": "2024-01-15T10:30:00Z"
  },
  "createdAt": "2024-01-01T00:00:00Z"
}

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#

GET /webhooks

Example Request#

curl https://api.bootspring.dev/v1/webhooks \
  -H "Authorization: Bearer bs_xxx"

Response#

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://example.com/webhooks/bootspring",
      "events": ["project.created", "agent.invoked"],
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Webhook#

POST /webhooks

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#

curl -X POST https://api.bootspring.dev/v1/webhooks \
  -H "Authorization: Bearer bs_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/bootspring",
    "events": ["project.created", "agent.invoked", "usage.threshold_reached"],
    "metadata": {
      "environment": "production"
    }
  }'

Response#

{
  "data": {
    "id": "wh_def456",
    "url": "https://example.com/webhooks/bootspring",
    "events": ["project.created", "agent.invoked", "usage.threshold_reached"],
    "status": "active",
    "secret": "whsec_abc123xyz...",
    "metadata": {
      "environment": "production"
    },
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Important: The secret is only shown once. Store it securely for signature verification.

Update Webhook#

PATCH /webhooks/:id

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#

curl -X PATCH https://api.bootspring.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer bs_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["project.created", "project.updated"],
    "status": "active"
  }'

Delete Webhook#

DELETE /webhooks/:id

Example Request#

curl -X DELETE https://api.bootspring.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer bs_xxx"

List Deliveries#

GET /webhooks/:id/deliveries

Query Parameters#

Parameter	Type	Description
`status`	string	Filter: `success`, `failed`, `pending`
`limit`	integer	Number of deliveries (default: 20)

Response#

{
  "data": [
    {
      "id": "del_xyz789",
      "event": "project.created",
      "status": "success",
      "statusCode": 200,
      "duration": 145,
      "attemptCount": 1,
      "request": {
        "headers": { "Content-Type": "application/json" },
        "body": "{...}"
      },
      "response": {
        "statusCode": 200,
        "body": "OK"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Send Test Event#

POST /webhooks/:id/test

Request Body#

Field	Type	Required	Description
`event`	string	Yes	Event type to simulate

Example Request#

curl -X POST https://api.bootspring.dev/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer bs_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "project.created"
  }'

Webhook Payload Format#

Headers#

POST /your-webhook-endpoint
Content-Type: application/json
X-Bootspring-Signature: sha256=abc123...
X-Bootspring-Delivery: del_xyz789
X-Bootspring-Event: project.created

Body#

{
  "id": "evt_abc123",
  "type": "project.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "project": {
      "id": "proj_xyz",
      "name": "New Project",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Signature Verification#

Verify webhook signatures to ensure requests are from Bootspring.

Node.js#

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const expected = `sha256=${expectedSignature}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhooks/bootspring', (req, res) => {
  const signature = req.headers['x-bootspring-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  const event = req.body;
  console.log(`Received ${event.type}:`, event.data);

  res.status(200).send('OK');
});

Python#

import hmac
import hashlib

def verify_webhook_signature(payload: str, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

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:

app.post('/webhooks', async (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

2. Handle Duplicates#

Webhooks may be delivered multiple times. Use the event id for idempotency:

const processedEvents = new Set();

async function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }

  processedEvents.add(event.id);
  // Process event...
}

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