Outbound Webhooks

Overview

Outbound webhooks let you receive HTTP POST notifications when specific events occur in your HolyDocs project. Use them to trigger CI/CD pipelines, update external systems, send notifications, or integrate with your existing toolchain.

Supported Events

Event	Description
deployment.started	A build has started
deployment.completed	A deployment finished successfully
deployment.failed	A deployment failed
page.created	A new documentation page was added
page.updated	An existing page was modified
page.deleted	A page was removed
feedback.received	A reader submitted page feedback
assistant.conversation.completed	An AI assistant conversation ended
agent.job.completed	An AI agent job finished

Creating a Webhook

Dashboard

1. Go to Settings > Webhooks in your project dashboard
2. Click Add Webhook
3. Enter the destination URL and select the events to subscribe to
4. Click Create Webhook

API

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/webhooks" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://your-server.com/hooks/holydocs",    "events": ["deployment.completed", "deployment.failed", "feedback.received"]  }'

Webhook Payload

Each webhook delivery is an HTTP POST request with a JSON body:

json
{  "id": "evt_abc123",  "event": "deployment.completed",  "timestamp": "2026-02-17T12:00:00.000Z",  "projectId": "proj_xyz",  "data": {    "deploymentId": "dep_456",    "status": "success",    "commitSha": "a1b2c3d",    "branch": "main",    "duration": 15000,    "pagesBuilt": 42  }}

Headers

Each webhook request includes these headers:

Header	Description
Content-Type	application/json
X-HolyDocs-Event	Event type (e.g., deployment.completed)
X-HolyDocs-Delivery	Unique delivery ID
X-HolyDocs-Signature	HMAC-SHA256 signature for verification

Signature Verification

Verify webhook authenticity by checking the X-HolyDocs-Signature header:

javascript
const crypto = require('crypto');function verifySignature(payload, signature, secret) {  const expected = crypto    .createHmac('sha256', secret)    .update(payload)    .digest('hex');  return crypto.timingSafeEqual(    Buffer.from(signature),    Buffer.from(expected)  );}// In your webhook handlerapp.post('/hooks/holydocs', (req, res) => {  const signature = req.headers['x-holydocs-signature'];  const isValid = verifySignature(    JSON.stringify(req.body),    signature,    process.env.WEBHOOK_SECRET  );  if (!isValid) {    return res.status(401).json({ error: 'Invalid signature' });  }  // Process the event  console.log(`Received ${req.body.event}`, req.body.data);  res.status(200).json({ ok: true });});

Testing Webhooks

Send a test event to verify your webhook endpoint is working:

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID/test" \  -H "Authorization: Bearer YOUR_API_KEY"

This sends a test.ping event to your endpoint with sample data.

Managing Webhooks

List Webhooks

bash
curl "https://api.holydocs.com/api/v1/projects/PROJECT_ID/webhooks" \  -H "Authorization: Bearer YOUR_API_KEY"

Update a Webhook

bash
curl -X PATCH "https://api.holydocs.com/api/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "events": ["deployment.completed", "deployment.failed"]  }'

Delete a Webhook

bash
curl -X DELETE "https://api.holydocs.com/api/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

Webhook deliveries are retried up to 3 times with exponential backoff if the endpoint returns a non-2xx status code. Failed deliveries are logged and visible in the dashboard.

Use Cases

• CI/CD triggers — Run tests or deploy downstream services after documentation updates
• Slack/Teams notifications — Forward deployment events to your team channels
• Analytics — Track documentation changes in your internal analytics system
• Content approval workflows — Trigger review processes when pages are updated
• Monitoring — Alert on deployment failures or negative feedback trends