Skip to main content

​
Webhooks

VitaRelay webhooks are outbound only. When something happens on an order or an intake, VitaRelay POSTs a signed JSON payload to the HTTPS endpoint configured for your organization. There is no polling required, and there is no webhook management API.
Webhook endpoints are configured by a VitaRelay admin in the dashboard (org profile → Webhooks panel). The admin sets the endpoint URL, selects which events you are subscribed to, and is shown the signing secret once at creation time. Ask your VitaRelay contact to set this up or to rotate the secret — you cannot register endpoints through the API.

​
How it works

1

An admin configures your endpoint

URL, subscribed events, and a signing secret (shown once).
2

An event occurs

An order is paid, ships, is delivered, hits a delivery exception, or a prescriber signs an escript.
3

VitaRelay POSTs the event

A JSON body is sent to your URL with HMAC-SHA256 signature headers.
4

You verify and acknowledge

Verify the signature over the raw body, return 2xx quickly, and process asynchronously.
5

Failures retry

Non-2xx responses and timeouts are retried with exponential backoff, then dead-lettered.

​
Events

Exactly five event types are emitted: Full payload examples are on the Event Types page.

​
Delivery headers

Every delivery includes:

​
At-least-once delivery

Deliveries are at-least-once. A retried delivery reuses the same X-VitaRelay-Delivery id, so treat that header as your idempotency key and make your handler safe to run twice.
Always verify X-VitaRelay-Signature before trusting a payload. An unsigned or mismatched request must be rejected.

Event Types

The five events and their exact payloads.

Receiving Deliveries

Building an endpoint that acknowledges fast.

Security

Verifying the HMAC-SHA256 signature.

Retries

Backoff behavior and dead-lettering.