# Openevidence Webhooks Events

> Configure OpenEvidence webhooks for async DeepConsult completion and events. Use when implementing webhook handlers, configuring async notifications, or setting up event-driven clinical AI workflows. Trigger with phrases like "openevidence webhook", "openevidence events", "deepconsult callback", "openevidence notifications".

- Skill: `micsapp/openevidence-webhooks-events` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add micsapp/openevidence-webhooks-events`
- Raw SKILL.md: https://api.skillmd.com/api/skills/micsapp/openevidence-webhooks-events/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: micsapp (https://skillmd.com/u/micsapp)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/micsapp/openevidence-webhooks-events

---

# OpenEvidence Webhooks & Events

## Table of Contents
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Instructions](#instructions)
- [Output](#output)
- [Error Handling](#error-handling)
- [Examples](#examples)
- [Resources](#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
```bash
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](${CLAUDE_SKILL_DIR}/references/implementation.md) for advanced patterns.

## Resources
- [OpenEvidence API Docs](https://docs.openevidence.com/)
- [Webhook Security Best Practices](https://webhooks.fyi/)