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

# Webhooks

> Receive store events in real time on your endpoint.

Vellaro can notify your backend whenever something happens in your store (order created,
paid, shipped, return requested, etc.), so you can keep ERPs, back-office systems, or
external pipelines in sync without polling.

## How it works

1. You register one or more **endpoints** (HTTPS URLs) from the admin panel, choosing the events.
2. Vellaro sends a `POST` to your URL on every subscribed event, with a JSON payload
   describing the event and the resource.
3. The request is **signed**: verify the signature with your secret before trusting the
   content.
4. Respond with `2xx` to acknowledge receipt; failed deliveries are retried.

## Payload (typical shape)

```json theme={null}
{
  "event": "order.paid",
  "id": "evt_...",
  "created_at": "2026-07-19T10:00:00Z",
  "data": { "order": { "id": "...", "status": "processing", "total": "1299.00" } }
}
```

## Common events

| Event                                  | When                |
| -------------------------------------- | ------------------- |
| `order.created`                        | new order           |
| `order.paid`                           | payment captured    |
| `order.shipped` / `order.delivered`    | shipment/delivery   |
| `order.cancelled` / `order.refunded`   | cancellation/refund |
| `return.requested` / `return.approved` | returns             |

<Tip>
  Webhook management (creating endpoints, selecting events, signing secret, delivery attempt
  logs) lives in the admin panel, and can also be driven via the
  [Admin API](/en/guides/admin-api) / [MCP](/en/ai-mcp).
</Tip>

<Note>
  Webhooks are not needed for delivering **digital products**: after payment, the API
  issues signed download links, documented in the [API Reference](/en/api-reference).
</Note>