Skip to main content

Webhooks & Polling

A webhook tells you something happened; GET tells you what. Decision events are thin doorbells that never carry clinical content.

Endpoints

Decision events use the webhook endpoints you already configure in the developer dashboard, with the same per-endpoint signing secrets and delivery log. Events are routed by environment: sandbox decisions go to your test endpoints only, live decisions to your production endpoints only. You only receive events for decisions your account created. If you also use the Prescribing API, the same endpoints receive both kinds of event; switch on type.

Events

TypeWhen
decision.answeredA physician (or, in the sandbox, the simulator) answered.
decision.canceledAn escalated decision was canceled, by you or by Appendix. Canceling a preview that was never escalated sends nothing.
decision.answered
POST <your webhook URL>
Content-Type: application/json
X-Appendix-Event: decision.answered
X-Appendix-Signature: sha256=4f1c…

{
  "id": "evt_…",
  "type": "decision.answered",
  "created": "2026-11-04T09:12:03Z",
  "sandbox": false,
  "data": {
    "decision_id": "dec_7Hq2…",
    "external_id": "case_8812",
    "status": "answered"
  }
}
decision.canceled
{
  "id": "evt_…",
  "type": "decision.canceled",
  "created": "2026-11-03T18:40:00Z",
  "sandbox": false,
  "data": { "decision_id": "dec_7Hq2…", "external_id": "case_8812", "status": "canceled" }
}
  • data carries only decision_id, external_id (when you set one) and status. Answers, questions and input are never in a webhook.
  • On a cancellation because identifying information was found (cancellation_reason: "phi_detected"), external_id is omitted from the event, since it may itself have been affected.
  • sandbox is true for events from test-key decisions.
  • New event types may be added. Ignore types you don't handle and return 2xx.

Verify the signature

Every delivery has X-Appendix-Event (the event type) and X-Appendix-Signature: sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with that endpoint's secret. Compute it over the exact bytes you received, before parsing, and compare in constant time.

import crypto from "node:crypto";
import express from "express";

const app = express();
const seen = new Set<string>(); // use your database in production

// Use the RAW body: re-serializing parsed JSON changes the bytes and breaks the HMAC.
app.post("/appendix/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", process.env.APPENDIX_WEBHOOK_SECRET!).update(req.body).digest("hex");
  const got = req.header("X-Appendix-Signature") ?? "";
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200); // acknowledge fast; do the work after

  if (!event.type.startsWith("decision.") || seen.has(event.id)) return;
  seen.add(event.id);

  const r = await fetch(`https://api.appendix.com/api/v1/decisions/${event.data.decision_id}`, {
    headers: { Authorization: `Bearer ${process.env.APPENDIX_API_KEY}` },
  });
  const decision = await r.json(); // authoritative state, including decision.physician
  // … store decision.physician.answers against event.data.external_id
});

Delivery guarantees

  • At least once. A delivery that fails (non-2xx, timeout or connection error) is retried with backoff over several hours. You may receive the same event more than once; deduplicate on id.
  • Not ordered. Don't infer state from arrival order.
  • Pull the content. On any event, call GET /api/v1/decisions/{decision_id} and treat that response as the source of truth.
  • Respond with a 2xx quickly and do slow work afterwards. Redirects are not followed, and only HTTPS endpoints are accepted.
Polling works too. Without webhooks, poll GET /api/v1/decisions/{id} or GET /api/v1/decisions?status=answered. Physicians answer within 24 hours of escalation, so a poll every few minutes is plenty in production. Polling is also the fallback if your endpoint was down.