Webhooks

Receive real-time notifications about events in ZenSearch.

Overview

Webhooks allow you to:

• Get notified when syncs complete
• Track document processing
• Monitor connector status
• Build integrations

Creating Webhooks

Endpoint

POST /v1/webhooks

Request Body

{
  "url": "https://your-server.com/webhook",
  "events": ["sync.completed", "document.indexed"],
  "secret": "your-webhook-secret"
}

Parameters

Parameter	Type	Required	Description
url	string	Yes	Endpoint URL
events	string[]	Yes	Events to subscribe
secret	string	No	Signing secret

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

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
  }
}

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

Managing Webhooks

List Webhooks

GET /v1/webhooks

Update Webhook

PUT /v1/webhooks/{id}

Delete Webhook

DELETE /v1/webhooks/{id}

Test Webhook

POST /v1/webhooks/{id}/test

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