Webhooks

Receive real-time HTTP notifications when events occur in BoundaryAI.

Available Events

Event	Trigger	Use Case
content.pushed	Content pushed via API	Sync to CRM, trigger workflows
survey.created	New data source created	Auto-setup in external tools
survey.published	Data source published	Notify team, start monitoring
series.created	New feedback group created	Initialize dashboards

Webhook Payload

{
  "event": "content.pushed",
  "timestamp": "2025-01-15T10:30:00.000000Z",
  "data": {
    "survey_series_id": 123,
    "survey_id": 456,
    "question_id": 789,
    "lines_pushed": 50,
    "api_key_id": 1
  }
}

HTTP Headers

Header	Value
X-Boundary-Signature	sha256={hmac_signature}
X-Boundary-Event	Event type (e.g., content.pushed)
Content-Type	application/json
User-Agent	BoundaryAI-Webhook/1.0

Verifying Signatures

Always verify the signature to confirm the webhook is from BoundaryAI:

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# Usage in Flask:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Boundary-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.headers.get('X-Boundary-Event')
    data = request.json
    # Process the webhook...
    return 'OK', 200

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// Usage in Express:
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-boundary-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-boundary-event'];
  const data = JSON.parse(req.body);
  // Process the webhook...
  res.status(200).send('OK');
});

Retry Policy

If your endpoint fails, we retry with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	15 minutes

After 10 consecutive failures, the webhook is automatically disabled.

---

Error Reference

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { }
  }
}

Error Codes

Authentication Errors (4xx)

Code	HTTP	Description	Solution
MISSING_AUTH	401	No Authorization header	Add Authorization: Bearer {key}
INVALID_AUTH_FORMAT	401	Malformed header	Use Bearer {key} format
INVALID_TOKEN	401	Key doesn't exist or wrong format	Check key, create new if needed
REVOKED_KEY	401	Key was revoked	Create a new API key

Permission Errors (4xx)

Code	HTTP	Description	Solution
INSUFFICIENT_PERMISSION	403	Key lacks required permission	Use key with correct permission
FORBIDDEN	403	Resource belongs to another org	Check IDs are correct

Resource Errors (4xx)

Code	HTTP	Description	Solution
SURVEY_SERIES_NOT_FOUND	404	Feedback group doesn't exist	Verify survey_series_id
SURVEY_NOT_FOUND	404	Data source doesn't exist	Verify survey_id
QUESTION_NOT_FOUND	404	Question doesn't exist	Verify question_id

Validation Errors (4xx)

Code	HTTP	Description	Solution
VALIDATION_ERROR	400	Invalid request data	Check details for specific fields
INVALID_QUESTION_TYPE	400	Pushing text to non-text question	Use question with accepts_text: true

Rate & Quota Errors (4xx)

Code	HTTP	Description	Solution
RATE_LIMITED	429	Too many requests	Wait for Retry-After seconds
INSUFFICIENT_APS	402	Not enough analysis points	Purchase more APS or use test key

Other Errors