Webhooks

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

Overview

Webhooks allow you to receive real-time notifications when events occur in BoundaryAI. Instead of polling our API, your server receives HTTP POST requests automatically.

Use cases:

• Sync pushed content to your data warehouse

• Trigger workflows when surveys are created/published

• Build real-time dashboards

• Integrate with Slack, Teams, or other tools

Prerequisites

1. Admin access - Only organization admins can manage webhooks

2. HTTPS endpoint - Your webhook URL must use HTTPS (HTTP not allowed)

3. Public URL - The URL must be publicly accessible (no localhost, private IPs, or internal domains)

4. Response time - Your endpoint should respond within 10 seconds

Available Events

Event	Description	When it fires
content.pushed	Content was pushed via API	After successful /api/input/content/push or /api/input/content/push/bulk
survey.created	A new survey was created	After successful /api/input/survey/create
survey.published	A survey was published	After successful /api/input/survey/publish
series.created	A new feedback group was created	After successful /api/input/survey_series/create

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

Every webhook request includes these headers:

Header	Description	Example
X-Boundary-Signature	HMAC-SHA256 signature for verification	sha256=abc123...
X-Boundary-Event	The event type that triggered this webhook	content.pushed
Content-Type	Always JSON	application/json
User-Agent	Identifies BoundaryAI as the sender	BoundaryAI-Webhook/1.0

Managing Webhooks

All webhook management endpoints require JWT authentication (not API key).

List Webhooks

GET /api/webhooks
Authorization: Bearer {JWT_TOKEN}

^Response

{
  "is_admin": true,
  "webhooks": [
    {
      "id": 1,
      "name": "My Webhook",
      "url": "https://example.com/webhook",
      "events": ["content.pushed", "survey.created"],
      "is_active": true,
      "failure_count": 0,
      "created_at": "2025-01-15T10:00:00+00:00",
      "last_triggered_at": null
    }
  ],
  "available_events": ["content.pushed", "survey.created", "survey.published", "series.created"]
}

Create Webhook

POST /api/webhooks
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "events": ["content.pushed", "survey.created"]
}

^Response

{
  "webhook": {
    "id": 1,
    "name": "My Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed", "survey.created"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  },
  "secret": "ngQCfdLY0Ykp0_OLrXlMhzPfYNo0WV1w9j4Imt1ddMM",
  "message": "Save the secret now! You will not be able to see it again."
}

⚠️ Important: Save the secret immediately - it's only shown once!

Update Webhook

PATCH /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Updated Name",
  "events": ["content.pushed"],
  "is_active": true
}

^Response

{
  "webhook": {
    "id": 1,
    "name": "Updated Name",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  }
}

Single Webhook

GET /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Response

{
  "webhook": {
    "id": 1,
    "name": "My Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": "2025-01-15T12:00:00+00:00"
  }
}

Delete Webhook

DELETE /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Response

{
  "message": "Webhook deleted successfully",
  "webhook_id": 1
}

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