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
• BYOM monitoring: Receive alerts when your own LLM credentials hit rate limits or fail, so you can respond to provider issues quickly
• Reduced polling: Eliminate the need to continuously check for updates

Setting up webhooks

Webhooks are configured per project within the Webhooks page in the Zep Dashboard sidebar.

Available events

Graph events

BYOM events

These events are specific to Bring Your Own LLM (BYOM) configurations. They notify you when requests using your own model credentials encounter rate limits or failures, so you can monitor and react to issues with your LLM provider configuration.

BYOM webhook events are aggregated rather than sent per-request. Zep accumulates events over a 60-second window and delivers a single webhook summarizing all occurrences in that period. This prevents webhook spam during bursts of errors or rate limiting.

Webhook payload schemas

Episode processed payload

episode.processed events include the following fields:

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

Batch completion payloads

ingest.batch.completed is fired by two different code paths and the payload differs depending on the source.

Batch API payload

Sent when a batch created via the Batch API finishes processing. The batch_id matches the value returned by batch.create().

Example payload:

1
{
2
  "event_name": "ingest.batch.completed",
3
  "account_uuid": "1811f9c5-336c-402a-964b-1a62faddc9c0",
4
  "project_uuid": "a3627577-88b1-46ed-bcb9-0e90ff32dba3",
5
  "batch_id": "52caee86-759e-4bc2-8d20-c5c1a8212368",
6
  "completed_at": "2026-05-05T18:16:34Z"
7
}

Legacy batch payload

Sent when a batch submitted through the deprecated graph.add_batch() or thread.add_messages_batch() methods finishes processing. The task_id matches the task UUID returned by those calls.

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

BYOM event payload

BYOM events (byom.rate_limited, byom.request_failed) include the following fields:

BYOM error codes

The error_code field in byom.request_failed events indicates the specific failure reason:

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
    elif event_name == "byom.rate_limited":
22
        # Handle BYOM rate limiting
23
        pass
24
    elif event_name == "byom.request_failed":
25
        # Handle BYOM request failure
26
        error_code = event.get("error_code")
27
        pass
28
29
    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