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):
text
signature = HMAC-SHA256(timestamp + "." + payload, secret)
Verification Steps#
- Extract timestamp from
X-Webhook-Timestampheader - Extract signature from
X-Webhook-Signatureheader - Construct signed payload:
{timestamp}.{raw_body} - Compute expected signature using your secret
- 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#
- Rotate secrets periodically (e.g., every 90 days)
- Store secrets securely (environment variables, secrets manager)
- Never log or expose secrets
- 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:
text
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:
text
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 - API authentication
- Error Codes - Error response format
- Rate Limits - API rate limiting