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 aggregated alerts when your LLM credentials or provider requests fail
• 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 apply to Bring Your Own LLM (BYOM) configurations. They report credential and provider failures for requests that use your credentials.

Zep aggregates BYOM webhook events instead of sending one webhook per request. Zep reports occurrences from a 60-second window in one webhook.

Webhook payload schemas

Episode processed payload

episode.processed events include the following fields:

*A payload for a user graph can include user_id. A payload for a graph with the graph type can include graph_id. Zep sends each field only when the user or graph has a developer-assigned identifier. A user or graph that the v4 API creates has no developer-assigned identifier. Its payload identifies the graph with graph_uuid and, for a user graph, with user_uuid.

Batch completion payloads

Zep sends one payload for every batch, including a batch that a deprecated batch method creates.

Batch API payload

Sent when a batch created via the Batch API finishes as succeeded, canceled, or partial from canceled items. Zep does not send this payload when a run ends as failed, or as partial because items failed. The batch_id matches the value returned by batch.create().

Example payload:

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

Deprecated batch methods

The deprecated graph.add_batch() and thread.add_messages_batch() methods create a Batch API batch. When that batch completes, Zep sends the Batch API payload above. The payload does not include task_id, episode_uuids, or graph identifiers. To match the payload to a call, compare batch_id with the batch_uuid value in the params of the task that the call returns.

BYOM event payload

byom.request_failed events 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 before the request times out
• Disable CSRF protection for the webhook route if your framework enables it by default

from flask import Flask, request
app = Flask(__name__)
@app.route("/webhooks/zep", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    headers = request.headers
    # Verify the webhook signature (see next section)
    # Process the event
    event = request.json
    event_name = event.get("event_name")
    if event_name == "episode.processed":
        # Handle episode processed event
        pass
    elif event_name == "ingest.batch.completed":
        # Handle batch completion event
        pass
    elif event_name == "byom.request_failed":
        # Handle BYOM request failure
        error_code = event.get("error_code")
        pass
    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:

from svix.webhooks import Webhook
# Your signing secret from the Zep Dashboard
WEBHOOK_SECRET = "whsec_..."
def verify_webhook(payload: str, headers: dict) -> dict:
    wh = Webhook(WEBHOOK_SECRET)
    # This will raise an exception if verification fails
    return wh.verify(payload, headers)
# In your webhook handler:
@app.route("/webhooks/zep", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    headers = {
        "svix-id": request.headers.get("svix-id"),
        "svix-timestamp": request.headers.get("svix-timestamp"),
        "svix-signature": request.headers.get("svix-signature"),
    }
    try:
        event = verify_webhook(payload, headers)
        # Process the verified event
        return "", 200
    except Exception as e:
        print(f"Webhook verification failed: {e}")
        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}

const crypto = require('crypto');
const signedContent = `${svixId}.${svixTimestamp}.${rawBody}`;
const secret = "whsec_...";
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const expectedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent)
    .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
• Acknowledge the request: Return a 2xx response before the request times out
• 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