# Webhooks

Reference documentation for the Lilith webhook system including registration,
event types, security, and delivery management.

## Overview

The Lilith webhook system provides:

- **Event Subscriptions**: Subscribe to content, entity, and system events
- **HMAC Signatures**: Secure payload verification with SHA-256/SHA-512
- **Automatic Retries**: Exponential backoff with configurable retry limits
- **Delivery Tracking**: Full history with statistics and monitoring
- **Event Filtering**: Selective event delivery based on content type, status,
  tags

## Quick Start

### Create a Webhook

```bash
curl -X POST https://api.lilith.app/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Content Webhook",
    "url": "https://example.com/webhooks/lilith",
    "events": ["content.created", "content.updated", "content.deleted"]
  }'
```

**Response:**

```json
{
  "id": "wh_abc123",
  "name": "My Content Webhook",
  "url": "https://example.com/webhooks/lilith",
  "secret": "whsec_def456ghi789...",
  "events": ["content.created", "content.updated", "content.deleted"],
  "status": "active",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

### Verify Signatures

```typescript
import crypto from 'crypto';

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}
```

## API Endpoints

### Webhook Management

| Method   | Endpoint           | Description                 |
| -------- | ------------------ | --------------------------- |
| `POST`   | `/v1/webhooks`     | Create webhook subscription |
| `GET`    | `/v1/webhooks`     | List webhooks (paginated)   |
| `GET`    | `/v1/webhooks/:id` | Get webhook details         |
| `PUT`    | `/v1/webhooks/:id` | Update webhook              |
| `PATCH`  | `/v1/webhooks/:id` | Partial update              |
| `DELETE` | `/v1/webhooks/:id` | Delete webhook              |

### Webhook Operations

| Method | Endpoint                         | Description                |
| ------ | -------------------------------- | -------------------------- |
| `POST` | `/v1/webhooks/:id/secret/rotate` | Regenerate secret          |
| `POST` | `/v1/webhooks/:id/test`          | Send test event            |
| `GET`  | `/v1/webhooks/:id/stats`         | Get delivery statistics    |
| `GET`  | `/v1/webhooks/:id/deliveries`    | Get delivery history       |
| `GET`  | `/v1/webhooks/events`            | List available event types |

## Create Webhook

```http
POST /v1/webhooks
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Content Updates",
  "url": "https://example.com/webhooks",
  "events": ["content.created", "content.updated"],
  "method": "POST",
  "format": "json",
  "headers": {
    "X-Custom-Header": "value"
  },
  "filters": {
    "contentTypes": ["meditation", "course"],
    "contentStatus": ["published"]
  },
  "retryConfig": {
    "maxRetries": 5,
    "retryDelayMs": 1000,
    "backoffMultiplier": 2,
    "maxDelayMs": 300000
  },
  "metadata": {
    "environment": "production"
  }
}
```

### Request Parameters

| Field         | Type     | Required | Description                               |
| ------------- | -------- | -------- | ----------------------------------------- |
| `name`        | string   | Yes      | Friendly webhook name                     |
| `url`         | string   | Yes      | Target endpoint URL                       |
| `events`      | string[] | Yes      | Event types to subscribe                  |
| `method`      | string   | No       | HTTP method (POST/PUT, default: POST)     |
| `format`      | string   | No       | Payload format (json/form, default: json) |
| `headers`     | object   | No       | Custom headers to include                 |
| `filters`     | object   | No       | Event filtering criteria                  |
| `retryConfig` | object   | No       | Custom retry configuration                |
| `metadata`    | object   | No       | Custom metadata                           |

### Response

```json
{
  "id": "wh_abc123",
  "name": "Content Updates",
  "url": "https://example.com/webhooks",
  "secret": "whsec_a1b2c3d4e5f6...",
  "events": ["content.created", "content.updated"],
  "status": "active",
  "method": "POST",
  "format": "json",
  "headers": {
    "X-Custom-Header": "value"
  },
  "filters": {
    "contentTypes": ["meditation", "course"],
    "contentStatus": ["published"]
  },
  "retryConfig": {
    "maxRetries": 5,
    "retryDelayMs": 1000,
    "backoffMultiplier": 2,
    "maxDelayMs": 300000
  },
  "consecutiveFailures": 0,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

## Event Types

### Content Events

| Event                      | Description           | Payload        |
| -------------------------- | --------------------- | -------------- |
| `content.created`          | New content published | Content object |
| `content.updated`          | Content modified      | Content object |
| `content.published`        | Content made public   | Content object |
| `content.unpublished`      | Content hidden        | Content object |
| `content.deleted`          | Content removed       | Content ID     |
| `content.version.created`  | New version created   | Version object |
| `content.version.restored` | Version restored      | Version object |

### Entity Events

| Event                         | Description          | Payload             |
| ----------------------------- | -------------------- | ------------------- |
| `entity.created`              | New entity created   | Entity object       |
| `entity.updated`              | Entity updated       | Entity object       |
| `entity.deleted`              | Entity deleted       | Entity ID           |
| `entity.relationship.created` | Relationship created | Relationship object |
| `entity.relationship.deleted` | Relationship removed | Relationship ID     |

### System Events

| Event                          | Description              | Payload         |
| ------------------------------ | ------------------------ | --------------- |
| `system.ping`                  | Test/health check        | Ping data       |
| `system.maintenance.scheduled` | Maintenance announcement | Schedule info   |
| `system.maintenance.completed` | Maintenance finished     | Completion info |

## Event Payload

### Standard Event Structure

```json
{
  "id": "evt_123456",
  "type": "content.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "content_id": "content_abc123",
    "title": "Morning Meditation",
    "type": "meditation",
    "status": "published",
    "author_id": "user_xyz789",
    "created_at": "2025-01-15T10:30:00.000Z"
  },
  "metadata": {
    "source": "api",
    "version": "1.0"
  }
}
```

### Content Event Data

```json
{
  "content_id": "content_abc123",
  "title": "Morning Meditation",
  "slug": "morning-meditation",
  "type": "meditation",
  "status": "published",
  "tradition": "mindfulness",
  "duration_seconds": 600,
  "author_id": "user_xyz789",
  "tags": ["morning", "beginner", "breath"],
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}
```

### Entity Event Data

```json
{
  "entity_id": "entity_abc123",
  "type": "person",
  "name": "Thich Nhat Hanh",
  "properties": {
    "tradition": "zen",
    "birth_year": 1926
  },
  "relationships": [{ "type": "authored", "target_id": "content_xyz789" }]
}
```

## Webhook Headers

Each webhook delivery includes these headers:

| Header                  | Description        | Example                      |
| ----------------------- | ------------------ | ---------------------------- |
| `X-Webhook-Id`          | Subscription ID    | `wh_abc123`                  |
| `X-Webhook-Event`       | Event type         | `content.created`            |
| `X-Webhook-Timestamp`   | ISO timestamp      | `2025-01-15T10:30:00.000Z`   |
| `X-Webhook-Signature`   | HMAC signature     | `sha256=a1b2c3...`           |
| `X-Webhook-Delivery-Id` | Unique delivery ID | `del_xyz789`                 |
| `User-Agent`            | Service identifier | `Lilith-Webhook-Service/1.0` |
| `Content-Type`          | Payload format     | `application/json`           |

## Signature Verification

### Algorithm

Webhooks are signed using HMAC-SHA256 (or SHA-512):

```
signature = HMAC-SHA256(timestamp + "." + payload, secret)
```

### Verification Steps

1. Extract timestamp from `X-Webhook-Timestamp` header
2. Extract signature from `X-Webhook-Signature` header
3. Construct signed payload: `{timestamp}.{raw_body}`
4. Compute expected signature using your secret
5. Compare using constant-time comparison

### Implementation Examples

**Node.js:**

```typescript
import crypto from 'crypto';

function verifySignature(
  payload: string,
  signature: string,
  secret: string,
  timestamp: string
): boolean {
  const signedPayload = `${timestamp}.${payload}`;

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const providedSig = signature.replace('sha256=', '');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig),
    Buffer.from(providedSig)
  );
}

// Express middleware
app.post(
  '/webhooks/lilith',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'] as string;
    const timestamp = req.headers['x-webhook-timestamp'] as string;
    const payload = req.body.toString();

    if (
      !verifySignature(
        payload,
        signature,
        process.env.WEBHOOK_SECRET,
        timestamp
      )
    ) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(payload);
    // Process event...

    res.status(200).json({ received: true });
  }
);
```

**Python:**

```python
import hmac
import hashlib

def verify_signature(payload: str, signature: str, secret: str, timestamp: str) -> bool:
    signed_payload = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    provided_sig = signature.replace('sha256=', '')

    return hmac.compare_digest(expected_sig, provided_sig)
```

**Go:**

```go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func verifySignature(payload, signature, secret, timestamp string) bool {
    signedPayload := timestamp + "." + payload
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signedPayload))
    expectedSig := hex.EncodeToString(mac.Sum(nil))

    providedSig := strings.TrimPrefix(signature, "sha256=")

    return hmac.Equal([]byte(expectedSig), []byte(providedSig))
}
```

## Retry Logic

### Default Configuration

| Setting             | Default | Description                    |
| ------------------- | ------- | ------------------------------ |
| `maxRetries`        | 5       | Maximum retry attempts         |
| `retryDelayMs`      | 1000    | Initial delay (1 second)       |
| `backoffMultiplier` | 2       | Exponential backoff multiplier |
| `maxDelayMs`        | 300000  | Maximum delay (5 minutes)      |

### Retry Schedule

| Attempt | Delay      | Total Time |
| ------- | ---------- | ---------- |
| 1       | Immediate  | 0          |
| 2       | 1 second   | 1s         |
| 3       | 2 seconds  | 3s         |
| 4       | 4 seconds  | 7s         |
| 5       | 8 seconds  | 15s        |
| 6       | 16 seconds | 31s        |

### Failure Handling

- Webhook disabled after 10 consecutive failures
- Automatic re-enable when secret is rotated
- Manual re-enable via API

### Successful Response

Webhooks expect a 2xx response within 30 seconds:

```json
{
  "received": true
}
```

## Event Filtering

Filter events to receive only relevant updates:

```json
{
  "filters": {
    "contentTypes": ["meditation", "course"],
    "contentStatus": ["published", "updated"],
    "entityTypes": ["person", "tradition"],
    "tags": ["beginner", "mindfulness"],
    "authorIds": ["user_abc123"],
    "traditions": ["zen", "vipassana"]
  }
}
```

### Filter Fields

| Field           | Description           | Example                    |
| --------------- | --------------------- | -------------------------- |
| `contentTypes`  | Content type filter   | `["meditation", "course"]` |
| `contentStatus` | Content status filter | `["published"]`            |
| `entityTypes`   | Entity type filter    | `["person"]`               |
| `tags`          | Tag filter            | `["beginner"]`             |
| `authorIds`     | Author filter         | `["user_abc123"]`          |
| `traditions`    | Tradition filter      | `["zen"]`                  |

## Delivery History

### Get Deliveries

```http
GET /v1/webhooks/:id/deliveries?limit=20&offset=0
```

**Response:**

```json
{
  "items": [
    {
      "id": "del_abc123",
      "subscriptionId": "wh_xyz789",
      "eventId": "evt_123456",
      "eventType": "content.created",
      "url": "https://example.com/webhooks",
      "status": "delivered",
      "attempt": 1,
      "responseStatus": 200,
      "responseBody": "{\"received\":true}",
      "durationMs": 245,
      "deliveredAt": "2025-01-15T10:30:01.000Z",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}
```

### Delivery Status

| Status      | Description                      |
| ----------- | -------------------------------- |
| `pending`   | Queued for delivery              |
| `delivered` | Successfully sent (2xx response) |
| `retrying`  | In retry queue                   |
| `failed`    | Permanently failed               |

## Statistics

### Get Webhook Statistics

```http
GET /v1/webhooks/:id/stats
```

**Response:**

```json
{
  "subscriptionId": "wh_abc123",
  "totalDeliveries": 1523,
  "successfulDeliveries": 1498,
  "failedDeliveries": 25,
  "avgResponseTimeMs": 187,
  "successRate": 98.36,
  "lastDeliveryStatus": "delivered",
  "lastDeliveryAt": "2025-01-15T10:30:00.000Z"
}
```

## Secret Management

### Rotate Secret

```http
POST /v1/webhooks/:id/secret/rotate
Authorization: Bearer <token>
```

**Response:**

```json
{
  "id": "wh_abc123",
  "secret": "whsec_new_secret_value...",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

### Best Practices

1. Rotate secrets periodically (e.g., every 90 days)
2. Store secrets securely (environment variables, secrets manager)
3. Never log or expose secrets
4. Update verification code before rotating

## Testing Webhooks

### Send Test Event

```http
POST /v1/webhooks/:id/test
Authorization: Bearer <token>

{
  "eventType": "system.ping",
  "data": {
    "message": "Test webhook delivery"
  }
}
```

**Response:**

```json
{
  "deliveryId": "del_test123",
  "status": "delivered",
  "responseStatus": 200,
  "durationMs": 125
}
```

### Local Development

For local testing, use a tunnel service:

```bash
# Using ngrok
ngrok http 3000

# Register webhook with tunnel URL
curl -X POST https://api.lilith.app/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Local Development",
    "url": "https://abc123.ngrok.io/webhooks",
    "events": ["content.created"]
  }'
```

## Payment Webhooks

### Stripe Webhooks

Stripe events are received at:

```
POST /webhooks/stripe
```

**Verification:**

```typescript
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

app.post(
  '/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];

    try {
      const event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );

      // Handle event...

      res.json({ received: true });
    } catch (err) {
      res.status(400).send(`Webhook Error: ${err.message}`);
    }
  }
);
```

### RevenueCat Webhooks

Mobile subscription events:

```
POST /webhooks/revenuecat
```

**Verification:**

```typescript
app.post('/webhooks/revenuecat', (req, res) => {
  const authHeader = req.headers.authorization;
  const expectedToken = `Bearer ${process.env.REVENUECAT_WEBHOOK_SECRET}`;

  if (authHeader !== expectedToken) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const event = req.body;
  // Handle event...

  res.json({ received: true });
});
```

## Error Handling

### Error Codes

| Code                        | HTTP Status | Description                    |
| --------------------------- | ----------- | ------------------------------ |
| `WEBHOOK_NOT_FOUND`         | 404         | Webhook subscription not found |
| `WEBHOOK_URL_INVALID`       | 400         | Invalid webhook URL            |
| `WEBHOOK_SIGNATURE_INVALID` | 401         | Signature verification failed  |
| `WEBHOOK_DELIVERY_FAILED`   | 500         | Delivery attempt failed        |
| `WEBHOOK_RATE_LIMITED`      | 429         | Too many requests              |
| `WEBHOOK_VALIDATION_FAILED` | 400         | Input validation error         |
| `WEBHOOK_QUOTA_EXCEEDED`    | 402         | Quota limit reached            |

### Error Response

```json
{
  "error": {
    "code": "WEBHOOK_URL_INVALID",
    "message": "The provided URL is not valid",
    "details": {
      "url": "invalid-url",
      "reason": "URL must start with https://"
    }
  }
}
```

## Best Practices

### 1. Always Verify Signatures

Never process webhooks without signature verification:

```typescript
if (!verifySignature(payload, signature, secret, timestamp)) {
  return res.status(401).json({ error: 'Invalid signature' });
}
```

### 2. Respond Quickly

Return 200 immediately, process asynchronously:

```typescript
app.post('/webhooks', (req, res) => {
  // Verify signature first
  if (!verifySignature(...)) {
    return res.status(401).end();
  }

  // Acknowledge receipt immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhookAsync(req.body);
});
```

### 3. Handle Idempotency

Use event IDs to prevent duplicate processing:

```typescript
const processedEvents = new Set();

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

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

### 4. Monitor Delivery Health

Track webhook health in your monitoring:

```typescript
// Check webhook stats periodically
const stats = await fetch(`/v1/webhooks/${webhookId}/stats`);
if (stats.successRate < 95) {
  alertOps('Webhook delivery degraded');
}
```

## Related Documentation

- [Authentication](./authentication.md) - API authentication
- [Error Codes](./error-codes.md) - Error response format
- [Rate Limits](./rate-limits.md) - API rate limiting
