> ## Documentation Index
> Fetch the complete documentation index at: https://api.vitarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> How VitaRelay sends signed outbound event notifications to your endpoint.

# Webhooks

VitaRelay webhooks are **outbound only**. When something happens on an order or
an intake, VitaRelay `POST`s a signed JSON payload to the HTTPS endpoint
configured for your organization. There is no polling required, and there is no
webhook management API.

<Note>
  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.
</Note>

## How it works

<Steps>
  <Step title="An admin configures your endpoint">
    URL, subscribed events, and a signing secret (shown once).
  </Step>

  <Step title="An event occurs">
    An order is paid, ships, is delivered, hits a delivery exception, or a
    prescriber signs an escript.
  </Step>

  <Step title="VitaRelay POSTs the event">
    A JSON body is sent to your URL with HMAC-SHA256 signature headers.
  </Step>

  <Step title="You verify and acknowledge">
    Verify the signature over the raw body, return `2xx` quickly, and process
    asynchronously.
  </Step>

  <Step title="Failures retry">
    Non-2xx responses and timeouts are retried with exponential backoff, then
    dead-lettered.
  </Step>
</Steps>

## Events

Exactly five event types are emitted:

| Event             | Fires when                                      |
| ----------------- | ----------------------------------------------- |
| `order.paid`      | An order's card-on-file charge succeeds         |
| `order.shipped`   | The order ships and tracking is attached        |
| `order.delivered` | The carrier reports delivery                    |
| `order.exception` | The carrier reports a delivery exception        |
| `intake.reviewed` | A prescriber **signs** the escript (Rx cleared) |

Full payload examples are on the [Event Types](/webhooks/events) page.

## Delivery headers

Every delivery includes:

```http theme={null}
Content-Type: application/json
X-VitaRelay-Signature: sha256=<hex hmac of the raw body>
X-VitaRelay-Event: order.shipped
X-VitaRelay-Delivery: 6a4a5f6c-6f4e-4b8b-9a9e-2f0d9b1f7a11
X-VitaRelay-Timestamp: 1751894400
```

## 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.

<Warning>
  Always verify `X-VitaRelay-Signature` before trusting a payload. An unsigned or
  mismatched request must be rejected.
</Warning>

<CardGroup cols={2}>
  <Card title="Event Types" href="/webhooks/events">
    The five events and their exact payloads.
  </Card>

  <Card title="Receiving Deliveries" href="/webhooks/inbound">
    Building an endpoint that acknowledges fast.
  </Card>

  <Card title="Security" href="/webhooks/security">
    Verifying the HMAC-SHA256 signature.
  </Card>

  <Card title="Retries" href="/webhooks/retries">
    Backoff behavior and dead-lettering.
  </Card>
</CardGroup>