openevidence-webhooks-events

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

Event Type	Description	Key Payload
deepconsult.started	Processing began	consultId, estimatedTime
deepconsult.progress	Progress update	consultId, progress (0-100)
deepconsult.completed	Finished successfully	consultId, report
deepconsult.failed	Processing failed	consultId, error, retryable
rate_limit.warning	Approaching rate limit	remaining, limit, resetAt
api_key.expiring	Key expiration warning	keyId, expiresAt

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 the concatenated timestamp and raw request body (joined by a period) with the 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

Webhook Issue	Detection	Resolution
Invalid signature	401 response	Check webhook secret configuration
Missing events	No handler called	Verify webhook registration
Duplicate processing	Multiple notifications	Enable idempotency tracking
Timeout	Webhook fails	Process async, return 200 immediately

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