OpenEvidence Webhooks & Events

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Configure webhooks for asynchronous OpenEvidence operations. Covers DeepConsult lifecycle events, signature verification, event handlers, idempotency, and webhook testing.

Prerequisites

• OpenEvidence Enterprise account with webhook access
• HTTPS endpoint for receiving webhooks
• Webhook secret for signature verification

Webhook Events

Instructions

Step 1: Create Webhook Endpoint

Set up Express route at /webhooks/openevidence with signature verification middleware. Parse t=timestamp,v1=signature format from x-openevidence-signature header.

Step 2: Implement Signature Verification

Compute HMAC-SHA256 of ${timestamp}.${payload} with webhook secret. Use timing-safe comparison. Reject timestamps older than 5 minutes (replay protection).

Step 3: Build Event Handlers

Create handlers for each event type: update database status for DeepConsult lifecycle, send push/email notifications on completion, alert ops on failures and rate limit warnings.

Step 4: Add Idempotency

Track processed webhook IDs in database with 24-hour TTL. Skip already-processed events to handle retries safely.

Step 5: Register Webhooks

Call client.webhooks.register() on app startup with endpoint URL, event list, and secret.

Output

• Secure webhook endpoint with HMAC-SHA256 verification
• Event handlers for all OpenEvidence webhook events
• Notification integration (push + email)
• Idempotency protection against duplicate processing
• Webhook registration on startup

Error Handling

Examples

Signature Format

x-openevidence-signature: t=1234567890,v1=abc123def456...  # 1234567890 = configured value

Quick Test

set -euo pipefail
# Generate test signature and POST to local endpoint
curl -X POST http://localhost:3000/webhooks/openevidence \  # 3000: 3 seconds in ms
  -H "Content-Type: application/json" \
  -H "x-openevidence-signature: t=$(date +%s),v1=TEST" \
  -d '{"event":"deepconsult.completed","data":{"consultId":"test"}}'

See detailed implementation for advanced patterns.

Resources

• OpenEvidence API Docs
• Webhook Security Best Practices