How to Set Up Webhooks

Set up webhooks to receive real-time notifications when events happen in your knowledge base. Automate workflows and keep external systems in sync with your Zuro content.

What Are Webhooks?

Webhooks are HTTP callbacks that notify your server when specific events occur in Zuro. Instead of polling for changes, Zuro sends data to your URL when events happen.

Available Events

You can subscribe to these webhook events:

Article Events

• article.created - New article is created
• article.updated - Article is updated
• article.deleted - Article is deleted
• article.approved - Article is approved
• article.rejected - Article is rejected

Knowledge Base Events

• knowledgebase.created - New knowledge base is created
• knowledgebase.updated - Knowledge base is updated
• knowledgebase.deleted - Knowledge base is deleted

Setting Up Webhooks

Step 1: Prepare Your Endpoint

1. Create an HTTP endpoint on your server
2. Ensure it accepts POST requests
3. Make it publicly accessible (HTTPS required)
4. Prepare to handle JSON payloads

Step 2: Create Webhook

1. Go to Settings → API → Webhooks
2. Click "Create Webhook"
3. Enter your webhook URL (must be HTTPS)
4. Select events to subscribe to
5. Click "Create"

Step 3: Save Your Secret

• Webhook secret is shown once when created
• Save it securely: You'll need it to verify signatures
• Store in environment variables: Never commit to code
• Regenerate if compromised: Create new webhook if secret is exposed

Webhook Payload

Payload Structure

{
  "event": "article.created",
  "timestamp": "2025-01-08T12:00:00Z",
  "data": {
    // Event-specific data
  }
}

Article Created Example

{
  "event": "article.created",
  "timestamp": "2025-01-08T12:00:00Z",
  "data": {
    "id": "article-id",
    "title": "Article Title",
    "slug": "article-slug",
    "knowledgeBase": "kb-id",
    "status": "draft",
    "author": "user-id"
  }
}

Signature Verification

Why Verify Signatures

Webhook signatures ensure requests are actually from Zuro and haven't been tampered with.

How to Verify

1. Get the signature from X-Zuro-Signature header
2. Get the webhook secret (saved when creating webhook)
3. Create HMAC SHA-256 hash of the request body
4. Compare with the signature header
5. Only process if signatures match

Example Verification (Node.js)

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  
  return hash === signature;
}

Webhook Management

Viewing Webhooks

1. Go to Settings → API → Webhooks
2. See all your webhooks
3. View last triggered time
4. Check failure count

Testing Webhooks

1. Use webhook testing tools (e.g., webhook.site)
2. Create a test webhook
3. Trigger events in Zuro
4. Verify payloads are received

Updating Webhooks

1. Find the webhook in settings
2. Click "Edit"
3. Update URL or events
4. Save changes

Deleting Webhooks

1. Find the webhook in settings
2. Click "Delete"
3. Confirm deletion
4. Webhook stops receiving events immediately

Handling Failures

Automatic Retry

• Zuro retries failed webhooks automatically
• Retries use exponential backoff
• Failed webhooks are deactivated after 5 consecutive failures

Monitoring

• Check "Last Triggered" timestamp
• Monitor "Failure Count"
• Review webhook logs on your server
• Set up alerts for failures

Reactivating

1. Fix the issue on your server
2. Go to webhook settings
3. Click "Reactivate" on failed webhook
4. Test to ensure it's working

Best Practices

Security

• Always use HTTPS: Webhooks require secure connections
• Verify signatures: Never process unverified webhooks
• Store secrets securely: Use environment variables
• Rotate secrets: Regenerate webhooks periodically

Reliability

• Handle errors gracefully: Return proper HTTP status codes
• Process asynchronously: Don't block webhook processing
• Idempotency: Handle duplicate events gracefully
• Logging: Log all webhook events for debugging

Performance

• Respond quickly: Return 200 status within 5 seconds
• Queue processing: Process webhooks in background
• Rate limiting: Handle high-volume events
• Monitoring: Track webhook performance

Common Use Cases

Content Sync

• Sync articles to external CMS
• Update search indexes
• Notify team members
• Update documentation sites

Automation

• Trigger CI/CD pipelines
• Update external databases
• Send notifications
• Create tickets in help desk

Analytics

• Track content changes
• Log events to analytics
• Update dashboards
• Generate reports

Troubleshooting

Webhooks Not Received

• Verify URL is publicly accessible
• Check URL uses HTTPS
• Review server logs for errors
• Test with webhook testing tool
• Check webhook is active in settings

Signature Verification Fails

• Verify you're using the correct secret
• Check signature header name (X-Zuro-Signature)
• Ensure request body matches exactly
• Review signature verification code

Webhook Deactivated

• Check failure count in settings
• Review server logs for errors
• Fix the issue on your server
• Reactivate the webhook
• Test to ensure it works