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

# Webhook

> Ricevi eventi del negozio in tempo reale sul tuo endpoint.

Vellaro può notificare il tuo backend quando succede qualcosa nel negozio (ordine creato,
pagato, spedito, reso richiesto, ecc.), così puoi sincronizzare ERP, gestionali o pipeline
esterne senza polling.

## Come funziona

1. Registri uno o più **endpoint** (URL HTTPS) dal pannello admin, scegliendo gli eventi.
2. Vellaro effettua una `POST` al tuo URL a ogni evento sottoscritto, con un payload JSON
   che descrive l'evento e la risorsa.
3. La richiesta è **firmata**: verifica la firma con il tuo secret prima di fidarti del
   contenuto.
4. Rispondi `2xx` per confermare la ricezione; gli invii falliti vengono ritentati.

## Payload (forma tipica)

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

## Eventi comuni

| Evento                                 | Quando              |
| -------------------------------------- | ------------------- |
| `order.created`                        | nuovo ordine        |
| `order.paid`                           | pagamento incassato |
| `order.shipped` / `order.delivered`    | spedizione/consegna |
| `order.cancelled` / `order.refunded`   | annullo/rimborso    |
| `return.requested` / `return.approved` | resi                |

<Tip>
  La gestione dei webhook (creazione endpoint, selezione eventi, secret di firma, log dei
  tentativi) è nel pannello admin, ed è anche pilotabile via
  [Admin API](/guides/admin-api) / [MCP](/ai-mcp).
</Tip>

<Note>
  Per la consegna dei **prodotti digitali** non servono webhook: dopo il pagamento l'API
  emette link di download firmati, documentati nella [API Reference](/api-reference).
</Note>