openevidence-webhooks-events

OpenEvidence Webhooks & Events

Overview

OpenEvidence delivers webhook notifications for clinical evidence retrieval workflows. Subscribe to events when queries complete, evidence bases are updated, new citations are added, or clinical reviews are flagged. Use these webhooks to keep clinical decision support systems current and trigger downstream audit workflows in real time.

Webhook Registration

const response = await fetch("https://api.openevidence.com/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENEVIDENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://yourapp.com/webhooks/openevidence",
    events: ["query.completed", "evidence.updated", "citation.added", "review.flagged"],
    secret: process.env.OPENEVIDENCE_WEBHOOK_SECRET,
  }),
});

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyOpenEvidenceSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-openevidence-signature"] as string;
  const expected = crypto.createHmac("sha256", process.env.OPENEVIDENCE_WEBHOOK_SECRET!)
    .update(req.body).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  next();
}

Event Handler

import express from "express";
const app = express();

app.post("/webhooks/openevidence", express.raw({ type: "application/json" }), verifyOpenEvidenceSignature, (req, res) => {
  const event = JSON.parse(req.body.toString());
  res.status(200).json({ received: true });

  switch (event.type) {
    case "query.completed":
      deliverResults(event.data.query_id, event.data.evidence_count); break;
    case "evidence.updated":
      refreshClinicalCache(event.data.topic_id, event.data.revision); break;
    case "citation.added":
      indexCitation(event.data.citation_id, event.data.pubmed_id); break;
    case "review.flagged":
      escalateReview(event.data.review_id, event.data.flag_reason); break;
  }
});

Event Types

Retry & Idempotency

const processed = new Set<string>();

async function handleIdempotent(event: { id: string; type: string; data: any }) {
  if (processed.has(event.id)) return;
  await routeEvent(event);
  processed.add(event.id);
  if (processed.size > 10_000) {
    const entries = Array.from(processed);
    entries.slice(0, entries.length - 10_000).forEach((id) => processed.delete(id));
  }
}

Error Handling

Resources

• OpenEvidence Platform

Next Steps

See openevidence-security-basics.