Eventi webhook

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.v2`	Attivato quando viene effettuato un nuovo ordine. Usa questo evento per le nuove integrazioni
`order.created`	Versione legacy di `order.created.v2` che invia l’oggetto ordine senza il consueto envelope `event`/`data`
`order.canceled`	Attivato quando un ordine viene annullato
`order.preparing`	Attivato quando un ordine passa allo stato in 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 affidato per la 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 dell’ordine
`order.completed`	Attivato quando un ordine viene contrassegnato come completato
`order.refund.created`	Attivato quando viene emesso un rimborso per un ordine
`order.refund.succeeded`	Attivato quando il gateway di pagamento conferma un rimborso dell’ordine
`order.refund.failed`	Attivato quando il gateway di pagamento rifiuta un rimborso dell’ordine

storekit non invia un evento order.accepted o order.rejected. Dopo order.created.v2, il successivo evento che ricevi per un ordine è il suo primo cambio di stato (order.preparing, order.ready_for_pickup, order.out_for_delivery, order.completed o order.canceled).

order.created.v2

Attivato quando un cliente effettua un nuovo ordine. Questo è l’evento a cui iscriversi per i nuovi ordini.

{
  "event": "order.created.v2",
  "data": {
    "id": "ord_abc123",
    "code": "A1B2",
    "asap": true,
    "total": 2500,
    "tip": 250,
    "deliveryFee": 299,
    "discountTotal": 0,
    "orderType": "Delivery",
    "channel": "WEB",
    "poNumber": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "deliveryTime": "2024-01-15T11:00:00Z",
    "pickUpTime": "2024-01-15T10:45:00Z",
    "notes": "Ring doorbell",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+44123456789",
      "marketingConsent": true
    },
    "items": [
      {
        "name": "Margherita Pizza",
        "printName": "Margherita",
        "price": 1200,
        "quantity": 1,
        "plu": null,
        "posId": null,
        "taxRate": 20,
        "note": "Extra crispy",
        "modifiers": [
          {
            "name": "Extra cheese",
            "printName": "Cheese",
            "price": 150,
            "quantity": 1,
            "plu": null,
            "posId": null,
            "taxRate": 20
          }
        ]
      }
    ],
    "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
        }
      }
    },
    "deliveryAddress": {
      "street1": "456 Oak Ave",
      "street2": "Flat 2",
      "city": "London",
      "postCode": "E1 6AN",
      "country": "UK",
      "notes": "Leave with reception",
      "coordinates": {
        "latitude": 51.5155,
        "longitude": -0.0722
      }
    }
  }
}

Campo	Descrizione
`orderType`	`InStore`, `Delivery`, `Pickup`, `Curbside`, `Billpay`, `CateringDelivery` o `CateringPickup`
`channel`	`WEB`, `PWA`, `APP` o `KIOSK`
`asap`	`true` quando l’ordine non era programmato per un orario successivo
`deliveryTime`	Orario stimato di evasione
`pickUpTime`	Solo ordini in consegna: quando il corriere deve ritirare dal negozio. Omesso per gli altri tipi di ordine
`deliveryAddress`	Solo ordini in consegna. Omesso per gli altri tipi di ordine
`table`	Solo ordini in loco: `{ id, name, posId, covers, area: { id, name, posId } }`. Omesso quando l’ordine non ha un tavolo
`customer.companyName`, `customer.vatNumber`	Presenti solo quando il cliente li ha forniti
`discountTotal`	Numero negativo in unità minori, oppure `0`
`items[].taxRate`, `items[].modifiers[].taxRate`	Aliquota fiscale dell’articolo padre

order.created

L’evento legacy per un nuovo ordine. Contiene gli stessi campi ordine di order.created.v2, ma li invia come body di primo livello senza wrapper event o data:

{
  "id": "ord_abc123",
  "code": "A1B2",
  "asap": true,
  "total": 2500,
  "orderType": "Pickup",
  "customer": { "...": "..." },
  "items": [ "..." ],
  "venue": { "...": "..." }
}

Entrambi gli eventi vengono inviati per ogni nuovo ordine. Iscriviti a order.created.v2 in modo che il tuo handler riceva la struttura standard del payload usata da ogni altro evento. order.created resta disponibile per le integrazioni esistenti.

order.canceled

Attivato quando un ordine viene annullato.

{
  "event": "order.canceled",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "canceled"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}

order.preparing

Attivato quando un ordine passa allo stato in preparazione.

{
  "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 da parte del cliente.

{
  "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.out_for_delivery

Attivato quando un ordine in consegna viene affidato al corriere.

{
  "event": "order.out_for_delivery",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "out_for_delivery"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}

order.completed

Attivato quando un ordine viene contrassegnato come completato. Si verifica per completamenti di singoli ordini (dalla dashboard, Deliverect, iKentoo o auto-update) così come per completamenti in blocco.

{
  "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.

{
  "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
  }
}

order.rating.updated

Attivato quando un cliente invia o aggiorna una valutazione per il proprio ordine.

{
  "event": "order.rating.updated",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+44123456789"
      }
    },
    "rating": 5,
    "comments": "Great food, fast delivery",
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "country": "UK",
        "companyName": "My Restaurant",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}

order.refund.created, order.refund.succeeded, order.refund.failed

order.refund.created si attiva quando viene emesso un rimborso dalla dashboard; a seguire order.refund.succeeded o order.refund.failed una volta che il gateway di pagamento lo elabora. Tutti e tre condividono la stessa forma e, a differenza di altri eventi, i campi si trovano accanto a event invece che dentro data:

{
  "event": "order.refund.created",
  "order": {
    "id": "ord_abc123",
    "total": 2500
  },
  "customer": {
    "id": "cus_123",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "venue": {
    "id": 1234,
    "name": "My Restaurant",
    "slug": "my-restaurant",
    "address": {
      "companyName": "My Restaurant",
      "street1": "99-101 Regent St",
      "street2": "Victory House",
      "city": "London",
      "postCode": "W1B 4EZ",
      "country": "UK"
    }
  },
  "refund": {
    "status": "pending",
    "amount": 1000,
    "totalAmountRefunded": 1000,
    "reason": "Item missing"
  }
}

customer.id e refund.reason sono null quando non disponibili.

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.

{
  "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",
        "country": "UK",
        "companyName": "My Restaurant",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}

store.closed

Attivato quando un negozio viene chiuso o messo in snooze.

{
  "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",
        "country": "UK",
        "companyName": "My Restaurant",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}

closedReason e closedUntil sono stringhe vuote quando il negozio è stato chiuso senza motivo o senza un orario di fine.

store.opening_hours.updated

Attivato quando gli orari di apertura vengono modificati per un negozio, dalla dashboard o da una sincronizzazione POS.

{
  "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",
        "country": "UK",
        "companyName": "My Restaurant",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    },
    "openingHours": [
      {
        "day": "monday",
        "openTime": "09:00:00",
        "closeTime": "22:00:00",
        "active": true
      }
    ],
    "specialHours": [
      {
        "date": "2024-12-25",
        "openTime": "12:00:00",
        "closeTime": "16:00:00",
        "active": false
      }
    ],
    "source": "dashboard"
  }
}

Campo	Descrizione
`openingHours[].day`	Uno tra `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`
`specialHours[].active`	`false` significa che il negozio è chiuso in quella data
`source`	`dashboard`, `toast` o `deliverect`

Eventi articolo

Eventi relativi alla disponibilità degli articoli di menu.

Evento	Descrizione
`item.out_of_stock`	Attivato quando un articolo del menu va esaurito

item.out_of_stock

Attivato quando un articolo del menu diventa non disponibile. Può accadere per diverse vie:

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 perché l’articolo è andato esaurito e source indica cosa lo ha attivato.

Motivo	Descrizione
`snoozed`	L’articolo è stato temporaneamente messo in snooze
`inventory_depleted`	L’inventario dell’articolo ha raggiunto zero
`disabled`	L’articolo è stato 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 di disponibilità POS generico

{
  "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, oppure null per snooze indefiniti)
inventory_depleted — {} vuoto
disabled — {} vuoto

Eventi pagamenti

Eventi relativi a pagamenti e payout.

Evento	Descrizione
`payments.payout.created`	Attivato quando viene inviato un payout al tuo conto bancario
`bill.payment.created`	Attivato quando viene creato un pagamento del 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 payment link
`payment_link.refund.succeeded`	Attivato quando un rimborso payment link viene confermato con successo dal gateway di pagamento
`payment_link.refund.failed`	Attivato quando un rimborso payment link viene rifiutato dal gateway di pagamento

payments.payout.created

Attivato quando storekit invia un payout al tuo conto bancario.

{
  "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": "1/2024"
  }
}

estimatedArrivalDate è una stringa mese/anno, oppure una stringa vuota quando il provider del payout non ne fornisce una.

payment_link.created

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

{
  "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 nel formato `plink_`
`paymentLink.type`	`one_off` o `reusable`
`paymentLink.amountType`	`fixed` o `variable`
`paymentLink.amount`	Importo fisso in unità minori di valuta, oppure `null` per i link variabili
`paymentLink.currency`	Codice valuta ISO 4217
`paymentLink.reference`	Il tuo riferimento interno, se impostato
`venue.slug`	Lo slug URL del venue

payment_link.paid

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

{
  "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 nel 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 in unità minori di valuta (ad es. penny)
`payment.pspReference`	Riferimento di pagamento Adyen
`venue.slug`	Lo slug URL del venue

payment_link.refund.created

Attivato quando viene avviato un rimborso per un pagamento payment link. A questo punto il rimborso è in stato pending — 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.

{
  "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 in unità minori di valuta (ad es. penny)
`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. Si attiva in modo asincrono dopo payment_link.refund.created.

{
  "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. Si attiva in modo asincrono dopo payment_link.refund.created.

{
  "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 cloud printer.

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 cloud printer connessa non riesce a contattare il server storekit per 5 minuti. Viene inoltre inviata una notifica email all’indirizzo email configurato del venue.

{
  "event": "printer.status.offline",
  "data": {
    "printer": {
      "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
      "name": "Kitchen Printer"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}

Una stampante condivisa da più negozi invia un evento per negozio.

printer.status.online

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

{
  "event": "printer.status.online",
  "data": {
    "printer": {
      "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
      "name": "Kitchen Printer"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Eventi webhook

Eventi ordine

order.created.v2

order.created

order.canceled

order.preparing

order.ready_for_pickup

order.out_for_delivery

order.completed

order.pos.dispatch.failed

order.rating.updated

order.refund.created, order.refund.succeeded, order.refund.failed

Eventi negozio

store.opened

store.closed

store.opening_hours.updated

Eventi articolo

item.out_of_stock

Eventi pagamenti

payments.payout.created

payment_link.created

payment_link.paid

payment_link.refund.created

payment_link.refund.succeeded

payment_link.refund.failed

Eventi stampante

printer.status.offline

printer.status.online

​Eventi ordine

​order.created.v2

​order.created

​order.canceled

​order.preparing

​order.ready_for_pickup

​order.out_for_delivery

​order.completed

​order.pos.dispatch.failed

​order.rating.updated

​order.refund.created, order.refund.succeeded, order.refund.failed

​Eventi negozio

​store.opened

​store.closed

​store.opening_hours.updated

​Eventi articolo

​item.out_of_stock

​Eventi pagamenti

​payments.payout.created

​payment_link.created

​payment_link.paid

​payment_link.refund.created

​payment_link.refund.succeeded

​payment_link.refund.failed

​Eventi stampante

​printer.status.offline

​printer.status.online

Eventi ordine

order.created.v2

order.created

order.canceled

order.preparing

order.ready_for_pickup

order.out_for_delivery

order.completed

order.pos.dispatch.failed

order.rating.updated

order.refund.created, order.refund.succeeded, order.refund.failed

Eventi negozio

store.opened

store.closed

store.opening_hours.updated

Eventi articolo

item.out_of_stock

Eventi pagamenti

payments.payout.created

payment_link.created

payment_link.paid

payment_link.refund.created

payment_link.refund.succeeded

payment_link.refund.failed

Eventi stampante

printer.status.offline

printer.status.online