Webhooks

Receive real-time notifications about events in ZenSearch via connector webhooks.

Overview

ZenSearch supports receiving webhooks from connected data sources to trigger real-time sync updates. When a document changes in a connected platform (e.g., a page is updated in Confluence, a file is modified in Google Drive), the source platform sends a webhook notification to ZenSearch, which processes the change immediately.

This enables near real-time search index updates without waiting for scheduled syncs.

How It Works

1. Configure webhooks in your source platform (e.g., GitHub, Confluence, Slack)
2. Point the webhook URL to your ZenSearch instance
3. When changes occur, the source platform notifies ZenSearch
4. ZenSearch processes only the changed content (incremental sync)

Supported Connectors

Connector	Webhook Support	Events
S3	Yes	Object created/modified/deleted
Google Drive	Yes	File changes
SharePoint	Yes	Document changes
Confluence	Yes	Page created/updated/deleted
Slack	Yes	Messages, file uploads
GitHub	Yes	Push, PR, issue events
Jira	Yes	Issue created/updated
Salesforce	Yes	Record changes
HubSpot	Yes	Object changes

Webhook Payload

Headers

X-Webhook-ID: wh_abc123
X-Webhook-Signature: sha256=...
X-Webhook-Timestamp: 1705766400
Content-Type: application/json

Body

{
  "id": "evt_abc123",
  "type": "sync.completed",
  "timestamp": "2024-01-20T14:00:00Z",
  "data": {
    "connectorId": "conn_xyz",
    "jobId": "job_123",
    "documentsProcessed": 150,
    "duration": 45000
  }
}

Event Types

Event	Description
sync.started	Sync job started
sync.completed	Sync job completed
sync.failed	Sync job failed
document.indexed	Document indexed
document.deleted	Document deleted
connector.created	Connector created
connector.deleted	Connector deleted

Verifying Signatures

Verify webhook authenticity using the signature:

Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Python

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature

Retry Policy

Failed deliveries are retried:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failures, the webhook is disabled.

Best Practices

1. Respond quickly: Return 2xx within 5 seconds
2. Process async: Queue events for processing
3. Verify signatures: Always validate authenticity
4. Handle duplicates: Events may be delivered multiple times
5. Monitor failures: Set up alerting for webhook failures

Next Steps

• Rate Limits - API limits
• Errors - Error handling