Webhooks
VitaRelay webhooks are outbound only. When something happens on an order or an intake, VitaRelayPOSTs 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, a
prescriber signs an escript, a subscription changes, or commission is tracked
for a partner.
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
You choose which events your endpoint receives; an admin subscribes it to the ones you want. Orders and intake
Partner accounts
Subscriptions and storefront
Commission events are a record for your own payouts — VitaRelay does not pay the
commission, and your own payout is not reduced by it.
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 sameX-VitaRelay-Delivery id, so treat that header as your idempotency key and make
your handler safe to run twice.
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.