Medevio Webhooks

Medevio can notify your system about events in a clinic by sending webhooks — HTTP POST requests to a URL you provide.

Subscribing

Webhook subscriptions are managed per clinic in the Medevio application, in Menu → Propojky → Konfigurace webhooků (https://my.medevio.dev/klinika/nastaveni/propojky). Each subscription binds one event type to one endpoint URL. Ask the clinic administrator to set it up there, or contact Medevio support.

Signing is opt-in and is turned on while the subscription is being created — the administrator ticks Podepisovat požadavky (HMAC) in the Nová konfigurace dialog, and the signing secret (Podpisový klíč) is displayed there once, immediately after the subscription is created. Ask them for it then; it is never shown again and no query returns it. The checkbox is present only in the new-subscription dialog — signing currently cannot be turned on for an existing subscription, turned off, or the secret rotated.

Delivery format

Every delivery is an HTTP POST to the subscribed URL with Content-Type: application/json and a common envelope:

{
  "event": "<event key>",
  "clinicId": "<clinic UUID>",
  "timestamp": "<ISO 8601 time the event was emitted>",
  "data": { "…event-specific payload…" }
}

The data shape of each event is documented on its own page. Requests are sent with User-Agent: Medevio-Webhook/1.0.

Responding

Respond with any 2xx status code within 30 seconds to acknowledge the delivery. The response body is ignored.

Retries

Failed deliveries (network errors, timeouts, 5xx, and 429 responses) are retried with exponential backoff (2 s, 4 s, 8 s, 16 s between attempts), up to 5 delivery attempts in total. Other 4xx responses are treated as permanent failures and are not retried. Deliveries may occasionally arrive more than once or out of order — make your handler idempotent, e.g. by deduplicating on the envelope (event, timestamp, entity ids in data).

Verifying signatures

When signing is enabled for a subscription, every delivery carries an X-Medevio-Signature header containing the lowercase hex HMAC-SHA256 digest of the raw request body, keyed with the subscription's signing secret — the value the clinic administrator was shown once when creating the subscription (see Subscribing above). Verify it by computing the digest over the exact received bytes (do not re-serialize the JSON) and comparing with a constant-time comparison:

const crypto = require('crypto')

const expected = crypto.createHmac('sha256', signingSecret).update(rawBody).digest('hex')
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))

Deliveries without signing enabled do not carry the header.

Testing

A subscription can be tested from the Medevio application; the test sends a webhook_test delivery (documented on its own page) to the subscribed URL.