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

# Eventi webhook

> Riferimento per ogni evento webhook storekit, inclusi ordine creato, accettato, rifiutato, rimborsato, articolo esaurito ed eventi di stato pagamento con relativi payload.

Questa pagina elenca tutti gli eventi webhook disponibili in storekit, raggruppati per categoria.

## Eventi ordine

Eventi relativi al ciclo di vita e alla gestione degli ordini.

| Evento                      | Descrizione                                                              |
| --------------------------- | ------------------------------------------------------------------------ |
| `order.created`             | Attivato quando un nuovo ordine viene effettuato                         |
| `order.accepted`            | Attivato quando un ordine viene accettato dal negozio                    |
| `order.rejected`            | Attivato quando un ordine viene rifiutato dal negozio                    |
| `order.canceled`            | Attivato quando un ordine viene cancellato                               |
| `order.preparing`           | Attivato quando un ordine passa allo stato di preparazione               |
| `order.ready_for_pickup`    | Attivato quando un ordine viene contrassegnato come pronto per il ritiro |
| `order.out_for_delivery`    | Attivato quando un ordine viene inviato in consegna                      |
| `order.pos.dispatch.failed` | Attivato quando un ordine non riesce a essere inviato a un sistema POS   |
| `order.rating.updated`      | Attivato quando un cliente aggiorna la valutazione del proprio ordine    |
| `order.completed`           | Attivato quando un ordine viene contrassegnato come completato           |
| `order.refund.created`      | Attivato quando viene emesso un rimborso per un ordine                   |

### order.created

Attivato quando un nuovo ordine viene effettuato da un cliente.

```json theme={null}
{
  "event": "order.created",
  "data": {
    "id": "ord_abc123",
    "code": "A1B2",
    "asap": true,
    "total": 2500,
    "tip": 250,
    "deliveryFee": 299,
    "discountTotal": 0,
    "orderType": "Pickup",
    "createdAt": "2024-01-15T10:30:00Z",
    "deliveryTime": "2024-01-15T11:00:00Z",
    "notes": "Ring doorbell",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+44123456789",
      "marketingConsent": true
    },
    "items": [
      {
        "name": "Margherita Pizza",
        "price": 1200,
        "quantity": 1,
        "plu": null,
        "posId": null,
        "taxRate": null,
        "modifiers": []
      }
    ],
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "123 Main St",
        "street2": "",
        "city": "London",
        "postCode": "W1A 1AA",
        "country": "UK",
        "companyName": "My Restaurant Ltd",
        "coordinates": {
          "latitude": 51.5074,
          "longitude": -0.1278
        }
      }
    },
    "table": {
      "id": "tbl_123",
      "name": "Table 5",
      "covers": 4,
      "posId": "pos_tbl_5",
      "area": {
        "id": "area_1",
        "name": "Main Floor",
        "posId": null
      }
    },
    "deliveryAddress": {
      "street1": "456 Oak Ave",
      "street2": "Flat 2",
      "city": "London",
      "postCode": "E1 6AN",
      "country": "UK",
      "coordinates": {
        "latitude": 51.5155,
        "longitude": -0.0722
      }
    }
  }
}
```

### order.accepted

Attivato quando un ordine viene accettato dal negozio. Ha la stessa struttura del payload di `order.created`.

### order.preparing

Attivato quando un ordine passa allo stato di preparazione.

```json theme={null}
{
  "event": "order.preparing",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "preparing"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.ready\_for\_pickup

Attivato quando un ordine viene contrassegnato come pronto per il ritiro del cliente.

```json theme={null}
{
  "event": "order.ready_for_pickup",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "ready_for_pickup"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.completed

Attivato quando un ordine viene contrassegnato come completato. Questo si attiva per completamenti di ordini individuali (tramite dashboard, Deliverect, iKentoo o auto-update) e per completamenti in blocco.

```json theme={null}
{
  "event": "order.completed",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "completed"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.pos.dispatch.failed

Attivato quando un ordine non riesce a essere inviato a un sistema POS.

```json theme={null}
{
  "event": "order.pos.dispatch.failed",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "total": 2500
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    },
    "pos": {
      "name": "Zonal",
      "error": "Connection timeout: Unable to reach POS endpoint"
    },
    "retryCount": 3
  }
}
```

***

## Eventi negozio

Eventi relativi allo stato e alla configurazione del negozio.

| Evento                        | Descrizione                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| `store.opened`                | Attivato quando un negozio apre, uno snooze termina in anticipo o uno snooze temporizzato scade |
| `store.closed`                | Attivato quando un negozio chiude o viene messo in snooze                                       |
| `store.opening_hours.updated` | Attivato quando gli orari di apertura vengono modificati                                        |

### store.opened

Attivato quando un negozio viene aperto, quando uno snooze viene terminato in anticipo o quando uno snooze temporizzato scade automaticamente.

```json theme={null}
{
  "event": "store.opened",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

### store.closed

Attivato quando un negozio viene chiuso o messo in snooze.

```json theme={null}
{
  "event": "store.closed",
  "data": {
    "closedReason": "Kitchen closing early",
    "closedUntil": "2024-01-15T18:00:00Z",
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

### store.opening\_hours.updated

Attivato quando gli orari di apertura vengono modificati per un negozio.

```json theme={null}
{
  "event": "store.opening_hours.updated",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

***

## Eventi articolo

Eventi relativi alla disponibilità degli articoli del menu.

| Evento              | Descrizione                                     |
| ------------------- | ----------------------------------------------- |
| `item.out_of_stock` | Attivato quando un articolo del menu è esaurito |

### item.out\_of\_stock

Attivato quando un articolo del menu diventa non disponibile. Ciò può avvenire attraverso diversi percorsi:

* **Snooze manuale** — un amministratore mette in snooze l'articolo dalla dashboard
* **Disabilitazione manuale** — un amministratore imposta la disponibilità dell'articolo su off
* **Esaurimento inventario** — l'inventario dell'articolo raggiunge zero dopo un ordine
* **Sincronizzazione integrazione** — un POS o un'integrazione (Deliverect, Lightspeed, Zonal) contrassegna l'articolo come non disponibile

Il campo `reason` indica il motivo per cui l'articolo è esaurito, e `source` indica cosa lo ha attivato.

| Motivo               | Descrizione                              |
| -------------------- | ---------------------------------------- |
| `snoozed`            | Articolo temporaneamente messo in snooze |
| `inventory_depleted` | Inventario dell'articolo esaurito        |
| `disabled`           | Articolo esplicitamente disabilitato     |

| Origine      | Descrizione                                            |
| ------------ | ------------------------------------------------------ |
| `manual`     | Azione eseguita da un amministratore nella dashboard   |
| `order`      | Inventario esaurito da un ordine cliente               |
| `deliverect` | Sincronizzato dall'integrazione Deliverect             |
| `lightspeed` | Sincronizzato dall'integrazione Lightspeed / iKentoo   |
| `zonal`      | Sincronizzato dal POS Zonal                            |
| `pos_sync`   | Sincronizzato da un push generico di disponibilità POS |

```json theme={null}
{
  "event": "item.out_of_stock",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant"
    },
    "item": {
      "id": 5678,
      "name": "Margherita Pizza",
      "plu": "PLU-001",
      "posId": "pos_item_42",
      "sku": "SKU-MARG-001"
    },
    "reason": "snoozed",
    "source": "manual",
    "details": {
      "snoozeEnd": "2024-01-15T18:00:00Z"
    }
  }
}
```

L'oggetto `details` varia in base al motivo:

* **`snoozed`** — include `snoozeEnd` (timestamp ISO 8601, o `null` per snooze a tempo indeterminato)
* **`inventory_depleted`** — `{}` vuoto
* **`disabled`** — `{}` vuoto

***

## Eventi di pagamento

Eventi relativi a pagamenti e payout.

| Evento                          | Descrizione                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `payments.payout.created`       | Attivato quando un payout viene inviato al tuo conto bancario                                       |
| `bill.payment.created`          | Attivato quando viene creato un pagamento di conto                                                  |
| `payment_link.created`          | Attivato quando viene creato un nuovo payment link                                                  |
| `payment_link.paid`             | Attivato quando un pagamento viene incassato con successo tramite un payment link                   |
| `payment_link.refund.created`   | Attivato quando viene avviato un rimborso per un pagamento tramite payment link                     |
| `payment_link.refund.succeeded` | Attivato quando un rimborso di payment link viene confermato come riuscito dal gateway di pagamento |
| `payment_link.refund.failed`    | Attivato quando un rimborso di payment link viene rifiutato dal gateway di pagamento                |

### payments.payout.created

Attivato quando storekit invia un payout al tuo conto bancario.

```json theme={null}
{
  "event": "payments.payout.created",
  "data": {
    "amounts": [
      {
        "currency": "GBP",
        "value": "3210.50"
      },
      {
        "currency": "GBP",
        "value": "1030.00"
      }
    ],
    "bankAccount": {
      "id": "db97e205-105c-42ff-8460-d06c25cb6830",
      "IBAN": "GB15HBUK40127612345678",
      "accountNumber": "0001234",
      "branchCode": "001234",
      "currency": "GBP"
    },
    "estimatedArrivalDate": "2024-01-17"
  }
}
```

### payment\_link.created

Attivato quando viene creato un nuovo payment link. Attivato solo per gli account con webhook abilitati.

```json theme={null}
{
  "event": "payment_link.created",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "type": "one_off",
      "amountType": "fixed",
      "amount": 2500,
      "currency": "GBP",
      "reference": "INV-001"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Campo                    | Descrizione                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `paymentLink.id`         | L'ID del payment link in formato `plink_`                                 |
| `paymentLink.type`       | `one_off` o `reusable`                                                    |
| `paymentLink.amountType` | `fixed` o `variable`                                                      |
| `paymentLink.amount`     | Importo fisso nell'unità minore della valuta, o `null` per link variabili |
| `paymentLink.currency`   | Codice valuta ISO 4217                                                    |
| `paymentLink.reference`  | Il tuo riferimento interno, se impostato                                  |
| `venue.slug`             | Lo slug URL della sede                                                    |

### payment\_link.paid

Attivato quando un pagamento viene incassato con successo tramite un payment link. Attivato solo per gli account con webhook abilitati.

```json theme={null}
{
  "event": "payment_link.paid",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "type": "one_off",
      "amountType": "fixed",
      "reference": "INV-001"
    },
    "payment": {
      "transactionId": "txn_abc123",
      "amount": 2500,
      "currency": "GBP",
      "pspReference": "ABCD1234EFGH5678"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Campo                    | Descrizione                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `paymentLink.id`         | L'ID del payment link in formato `plink_`                       |
| `paymentLink.type`       | `one_off` o `reusable`                                          |
| `paymentLink.amountType` | `fixed` o `variable`                                            |
| `paymentLink.reference`  | Il tuo riferimento interno, se impostato                        |
| `payment.amount`         | Importo incassato nell'unità minore della valuta (ad es. pence) |
| `payment.pspReference`   | Riferimento di pagamento Adyen                                  |
| `venue.slug`             | Lo slug URL della sede                                          |

### payment\_link.refund.created

Attivato quando viene avviato un rimborso per un pagamento tramite payment link. Il rimborso è in sospeso a questo punto: la conferma arriva tramite `payment_link.refund.succeeded` o `payment_link.refund.failed` una volta che il gateway di pagamento lo elabora in modo asincrono.

```json theme={null}
{
  "event": "payment_link.refund.created",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Campo                  | Descrizione                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| `refund.id`            | L'ID del rimborso                                                  |
| `refund.transactionId` | L'ID transazione del pagamento originale                           |
| `refund.amount`        | Importo del rimborso nell'unità minore della valuta (ad es. pence) |
| `refund.currency`      | Codice valuta ISO 4217                                             |
| `refund.reason`        | Motivo del rimborso, se fornito                                    |

### payment\_link.refund.succeeded

Attivato quando il gateway di pagamento conferma che un rimborso è stato elaborato con successo. Questo si attiva in modo asincrono dopo `payment_link.refund.created`.

```json theme={null}
{
  "event": "payment_link.refund.succeeded",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### payment\_link.refund.failed

Attivato quando il gateway di pagamento rifiuta un rimborso. Questo si attiva in modo asincrono dopo `payment_link.refund.created`.

```json theme={null}
{
  "event": "payment_link.refund.failed",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

***

## Eventi stampante

Eventi relativi allo stato delle stampanti cloud.

| Evento                   | Descrizione                                |
| ------------------------ | ------------------------------------------ |
| `printer.status.offline` | Attivato quando una stampante va offline   |
| `printer.status.online`  | Attivato quando una stampante torna online |

### printer.status.offline

Attivato quando una stampante cloud collegata non riesce a effettuare il check-in con il server storekit per 5 minuti. Viene inviata anche una notifica via email all'indirizzo email configurato per la sede.

```json theme={null}
{
  "event": "printer.status.offline",
  "data": {
    "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
    "mac": "00-B0-D0-63-C2-26",
    "model": "StarMCPrint3",
    "name": "Kitchen Printer",
    "status": "offline"
  }
}
```

### printer.status.online

Attivato quando una stampante cloud si riconnette ai nostri server dopo essere stata offline per almeno 5 minuti. Viene inviata anche una notifica via email per confermare che la stampante è tornata online.

```json theme={null}
{
  "event": "printer.status.online",
  "data": {
    "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
    "mac": "00-B0-D0-63-C2-26",
    "model": "StarMCPrint3",
    "name": "Kitchen Printer",
    "status": "online"
  }
}
```


## Related topics

- [Crea e condividi link di pagamento storekit](/docs/it/guides/payments/payment-links.md)
- [Configurazione dei webhook](/docs/it/developers/webhooks/setting-up-webhooks.md)
- [Introduzione per sviluppatori](/docs/it/developers/introduction.md)
- [Feedback dei clienti, valutazioni a stelle e recensioni smart](/docs/it/guides/marketing/customer-feedback.md)
- [Testare i webhook](/docs/it/developers/webhooks/testing-webhooks.md)