# Medplum Webhooks

Receive signed Medplum FHIR Subscription notifications.

## When to Use This Skill

* Configure a receiver for Medplum webhook deliveries.
* Diagnose `x-signature` verification failures.
* Handle `create`, `update`, `delete`.

## Setup

Create an active FHIR Subscription with channel.type rest-hook, your channel.endpoint and the criteria you want. Add https://www.medplum.com/fhir/StructureDefinition/subscription-secret with valueString set to a strong secret, and configure the same value in the receiver.

Add a subscription-secret extension to the Medplum Subscription. Without it, deliveries are unsigned and fail verification.

Set `MEDPLUM_WEBHOOK_SECRET` in the server environment. Read [setup](https://github.com/hookdeck/webhook-skills/blob/main/skills/medplum-webhooks/references/setup.md) before enabling delivery.

## Verification (core)

`x-signature` contains a bare hex digest over the raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.

After extracting the documented digest and constructing `message` as described in [verification](https://github.com/hookdeck/webhook-skills/blob/main/skills/medplum-webhooks/references/verification.md), the comparison is:

```javascript
const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);

```

No timestamp is included in the signed message. These examples do not invent an age check from unsigned fields.

Complete handlers and tests: [Express](https://github.com/hookdeck/webhook-skills/tree/main/skills/medplum-webhooks/examples/express/), [Next.js](https://github.com/hookdeck/webhook-skills/tree/main/skills/medplum-webhooks/examples/nextjs/), [FastAPI](https://github.com/hookdeck/webhook-skills/tree/main/skills/medplum-webhooks/examples/fastapi/).

## Event Handling

The body is a FHIR resource; dispatch on resourceType. There is no create/update/delete discriminator. Delete notifications contain {}. X-Medplum-Deleted-Resource supplies the resource type/id, but is unsigned because the HMAC covers only the body. Reconcile it with application state before acting; these examples do not trust that header as an authenticated identifier.

Use the Subscription extensions to configure retry behaviour. Queue accepted work durably and keep clinical data out of logs. Signatures are optional at the sender, but these examples require signing to be enabled.

## Local Development

```bash
npx hookdeck-cli listen 3000 medplum --path /webhooks/medplum

```

Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.

## Resources

* [Overview and event routing](https://github.com/hookdeck/webhook-skills/blob/main/skills/medplum-webhooks/references/overview.md)
* [Endpoint and secret setup](https://github.com/hookdeck/webhook-skills/blob/main/skills/medplum-webhooks/references/setup.md)
* [Verification and troubleshooting](https://github.com/hookdeck/webhook-skills/blob/main/skills/medplum-webhooks/references/verification.md)