Webhooks

Webhooks allow your application to receive real-time notifications when specific events occur in Zep, such as when an episode finishes processing or a batch ingestion completes. Instead of polling for changes, Zep pushes event data directly to your server as HTTP POST requests.

Why use webhooks

Webhooks enable event-driven architectures where your application reacts immediately to changes:

• Episode processed notifications: Trigger downstream processing when new data is added to a graph
• Batch completion alerts: Know when large data imports finish so you can start using the data
• Reduced polling: Eliminate the need to continuously check for updates

Setting up webhooks

Webhooks are configured per project in the Zep Dashboard.

Available events

Additional events will be added in the future.

Webhook payload schema

Every webhook payload includes the following fields:

*Only one of graph_id or user_id will be present in a given payload, depending on the graph type.

Receiving webhooks

Your webhook endpoint must:

• Accept HTTP POST requests
• Return a 2xx status code (200-299) within 15 seconds to acknowledge receipt
• Disable CSRF protection for the webhook route if your framework enables it by default

1
from flask import Flask, request
2
3
app = Flask(__name__)
4
5
@app.route("/webhooks/zep", methods=["POST"])
6
def handle_webhook():
7
    payload = request.get_data(as_text=True)
8
    headers = request.headers
9
10
    # Verify the webhook signature (see next section)
11
    # Process the event
12
    event = request.json
13
    event_name = event.get("event_name")
14
15
    if event_name == "episode.processed":
16
        # Handle episode processed event
17
        pass
18
    elif event_name == "ingest.batch.completed":
19
        # Handle batch completion event
20
        pass
21
22
    return "", 200

Verifying webhook signatures

Zep signs every webhook with a cryptographic signature using your endpoint’s signing secret. Verifying this signature ensures that:

• The webhook genuinely came from Zep
• The payload hasn’t been tampered with in transit

Using the Svix libraries (recommended)

Zep uses Svix to manage webhooks. The easiest way to verify signatures is with the Svix client libraries.

First, install the Svix library:

$
pip install svix

Then verify incoming webhooks:

1
from svix.webhooks import Webhook
2
3
# Your signing secret from the Zep Dashboard
4
WEBHOOK_SECRET = "whsec_..."
5
6
def verify_webhook(payload: str, headers: dict) -> dict:
7
    wh = Webhook(WEBHOOK_SECRET)
8
9
    # This will raise an exception if verification fails
10
    return wh.verify(payload, headers)
11
12
# In your webhook handler:
13
@app.route("/webhooks/zep", methods=["POST"])
14
def handle_webhook():
15
    payload = request.get_data(as_text=True)
16
    headers = {
17
        "svix-id": request.headers.get("svix-id"),
18
        "svix-timestamp": request.headers.get("svix-timestamp"),
19
        "svix-signature": request.headers.get("svix-signature"),
20
    }
21
22
    try:
23
        event = verify_webhook(payload, headers)
24
        # Process the verified event
25
        return "", 200
26
    except Exception as e:
27
        print(f"Webhook verification failed: {e}")
28
        return "", 400

Manual verification

If you prefer not to use the Svix libraries, you can verify signatures manually using HMAC-SHA256.

Every webhook includes three headers for verification:

• svix-id: Unique message identifier
• svix-timestamp: Unix timestamp (seconds since epoch)
• svix-signature: Base64-encoded signatures (may include multiple, comma-separated)

{svix-id}.{svix-timestamp}.{raw-body}

1
const crypto = require('crypto');
2
3
const signedContent = `${svixId}.${svixTimestamp}.${rawBody}`;
4
const secret = "whsec_...";
5
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
6
const expectedSignature = crypto
7
    .createHmac('sha256', secretBytes)
8
    .update(signedContent)
9
    .digest('base64');

For more details on manual verification, see the Svix documentation on manual verification.

Managing webhooks

The Webhooks tab in the Zep Dashboard provides several management features:

• Disable/Enable: Temporarily stop receiving events without deleting your endpoint configuration
• Activity logs: View the history of webhook deliveries and their status
• Replay messages: Re-send failed webhooks for debugging or recovery
• Rate limiting: Configure throttling to control the rate of incoming webhooks
• Delete: Remove an endpoint entirely

Pricing

Webhook deliveries consume credits. See the Zep pricing page for costs.

Best practices

• Always verify signatures: Treat unverified webhooks as potentially malicious
• Respond quickly: Return a 2xx response within 15 seconds to avoid timeout retries
• Process asynchronously: If handling takes longer than a few seconds, acknowledge receipt immediately and process the event in a background job
• Handle duplicates: Webhooks may occasionally be delivered more than once; use the svix-id header to deduplicate
• Monitor failures: Check the activity logs in the Dashboard to identify and fix delivery issues

Further reading

For additional information on consuming webhooks:

• Why verify webhooks - Security considerations explained
• Svix webhook verification libraries - Full library documentation
• Manual verification guide - Detailed manual verification steps