Eve library

Webhooks

Guide

Revision 1

On this page

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#

  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:

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');
}