> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Webhooks

Configure outbound webhooks to receive real-time notifications when events occur in your HolyDocs project.

## 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 handler
app.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