Skip to main content

Receiving Deliveries

Your endpoint is the inbound side of VitaRelay’s outbound webhooks: VitaRelay POSTs events to the URL a VitaRelay admin configured for your organization, and your server receives them.
You cannot register or edit endpoints through the API. A VitaRelay admin sets the URL and subscribed events in the dashboard and shows you the signing secret once.

Endpoint requirements

1

Accept POST over HTTPS

The body is JSON; read the raw bytes before parsing.
2

Verify the signature first

Compare against X-VitaRelay-Signature before doing anything else. See Security.
3

Dedupe on X-VitaRelay-Delivery

Retries reuse the same delivery id. Skip work you’ve already done.
4

Return 2xx fast

Acknowledge within a few seconds; do heavy work asynchronously.

Minimal handler

Routing by event type

Do not run long fulfillment, billing, or EHR writes inline. Slow handlers time out, which triggers retries and can eventually dead-letter the delivery.

Testing

Point a sandbox-configured endpoint at your handler and use a vr_test_ key. Sandbox objects advance through a simulated lifecycle and fire the same events with "sandbox": true. See Sandbox.