Événements webhook

Cette page liste tous les événements webhook disponibles dans storekit, regroupés par catégorie.

Événements de commande

Événements liés au cycle de vie et à la gestion des commandes.

Événement	Description
`order.created.v2`	Déclenché lorsqu’une nouvelle commande est passée. Utilisez cet événement pour les nouvelles intégrations
`order.created`	Version héritée d’`order.created.v2` qui envoie l’objet commande sans l’enveloppe standard `event`/`data`
`order.canceled`	Déclenché lorsqu’une commande est annulée
`order.preparing`	Déclenché lorsqu’une commande passe au statut « en préparation »
`order.ready_for_pickup`	Déclenché lorsqu’une commande est marquée comme prête pour retrait
`order.out_for_delivery`	Déclenché lorsqu’une commande est expédiée en livraison
`order.pos.dispatch.failed`	Déclenché lorsqu’une commande n’a pas pu être transmise à un système POS
`order.rating.updated`	Déclenché lorsqu’un client met à jour la note de sa commande
`order.completed`	Déclenché lorsqu’une commande est marquée comme terminée
`order.refund.created`	Déclenché lorsqu’un remboursement est émis pour une commande
`order.refund.succeeded`	Déclenché lorsque la passerelle de paiement confirme le remboursement d’une commande
`order.refund.failed`	Déclenché lorsque la passerelle de paiement rejette le remboursement d’une commande

storekit n’envoie pas d’événement order.accepted ni order.rejected. Après order.created.v2, le prochain événement que vous recevez pour une commande est son premier changement de statut (order.preparing, order.ready_for_pickup, order.out_for_delivery, order.completed ou order.canceled).

order.created.v2

Déclenché lorsqu’un client passe une nouvelle commande. C’est l’événement auquel s’abonner pour les nouvelles commandes.

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

Champ	Description
`orderType`	`InStore`, `Delivery`, `Pickup`, `Curbside`, `Billpay`, `CateringDelivery` ou `CateringPickup`
`channel`	`WEB`, `PWA`, `APP` ou `KIOSK`
`asap`	`true` lorsque la commande n’a pas été planifiée pour une heure ultérieure
`deliveryTime`	Heure de préparation estimée
`pickUpTime`	Commandes en livraison uniquement : moment où le coursier doit récupérer la commande au magasin. Omis pour les autres types de commande
`deliveryAddress`	Commandes en livraison uniquement. Omis pour les autres types de commande
`table`	Commandes sur place uniquement : `{ id, name, posId, covers, area: { id, name, posId } }`. Omis lorsque la commande n’a pas de table
`customer.companyName`, `customer.vatNumber`	Présents uniquement lorsque le client les a fournis
`discountTotal`	Nombre négatif en unités mineures, ou `0`
`items[].taxRate`, `items[].modifiers[].taxRate`	Taux de taxe de l’article parent

order.created

L’événement historique de nouvelle commande. Il transporte les mêmes champs de commande que order.created.v2, mais les envoie comme corps racine sans wrapper event ou data :

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

Les deux événements sont envoyés pour chaque nouvelle commande. Abonnez-vous à order.created.v2 pour que votre handler reçoive la structure de payload standard utilisée par tous les autres événements. order.created reste disponible pour les intégrations existantes.

order.canceled

Déclenché lorsqu’une commande est annulée.

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

order.preparing

Déclenché lorsqu’une commande passe au statut « en préparation ».

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

Déclenché lorsqu’une commande est marquée comme prête pour le retrait par le client.

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

Déclenché lorsqu’une commande en livraison est expédiée.

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

Déclenché lorsqu’une commande est marquée comme terminée. Cet événement se déclenche aussi bien pour les complétions individuelles (via le tableau de bord, Deliverect, iKentoo ou la mise à jour automatique) que pour les complétions groupées.

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

Déclenché lorsqu’une commande n’a pas pu être transmise à un système 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

Déclenché lorsqu’un client soumet ou met à jour une note pour sa commande.

{
  "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 se déclenche lorsqu’un remboursement est émis depuis le tableau de bord ; order.refund.succeeded ou order.refund.failed suit une fois que la passerelle de paiement l’a traité. Les trois partagent la même structure, et contrairement aux autres événements, les champs se trouvent à côté de event plutôt qu’à l’intérieur de 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 et refund.reason sont null lorsqu’ils ne sont pas disponibles.

Événements de magasin

Événements liés au statut et à la configuration du magasin.

Événement	Description
`store.opened`	Déclenché lorsqu’un magasin ouvre, qu’une mise en pause se termine plus tôt ou qu’une pause programmée expire
`store.closed`	Déclenché lorsqu’un magasin ferme ou est mis en pause
`store.opening_hours.updated`	Déclenché lorsque les horaires d’ouverture sont modifiés

store.opened

Déclenché lorsqu’un magasin est ouvert, lorsqu’une pause est terminée plus tôt, ou lorsqu’une pause programmée expire automatiquement.

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

Déclenché lorsqu’un magasin est fermé ou mis en pause.

{
  "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 et closedUntil sont des chaînes vides lorsque le magasin a été fermé sans motif ou sans heure de fin.

store.opening_hours.updated

Déclenché lorsque les horaires d’ouverture d’un magasin sont modifiés, depuis le tableau de bord ou par une synchronisation 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"
  }
}

Champ	Description
`openingHours[].day`	L’une des valeurs suivantes : `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`
`specialHours[].active`	`false` signifie que le magasin est fermé à cette date
`source`	`dashboard`, `toast` ou `deliverect`

Événements d’article

Événements liés à la disponibilité des articles du menu.

Événement	Description
`item.out_of_stock`	Déclenché lorsqu’un article du menu est en rupture de stock

item.out_of_stock

Déclenché lorsqu’un article du menu devient indisponible. Cela peut se produire par plusieurs biais :

Mise en pause manuelle — un administrateur met l’article en pause depuis le tableau de bord
Désactivation manuelle — un administrateur bascule la disponibilité de l’article sur off
Épuisement de l’inventaire — l’inventaire de l’article atteint zéro après une commande
Synchronisation d’intégration — un POS ou une intégration (Deliverect, Lightspeed, Zonal) marque l’article comme indisponible

Le champ reason indique pourquoi l’article est en rupture de stock, et source indique ce qui l’a déclenché.

Reason	Description
`snoozed`	L’article a été temporairement mis en pause
`inventory_depleted`	L’inventaire de l’article a atteint zéro
`disabled`	L’article a été explicitement désactivé

Source	Description
`manual`	Action effectuée par un administrateur dans le tableau de bord
`order`	Inventaire épuisé par une commande client
`deliverect`	Synchronisé depuis l’intégration Deliverect
`lightspeed`	Synchronisé depuis l’intégration Lightspeed / iKentoo
`zonal`	Synchronisé depuis le POS Zonal
`pos_sync`	Synchronisé depuis un push générique de disponibilité POS

{
  "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’objet details varie selon le motif :

snoozed — inclut snoozeEnd (horodatage ISO 8601, ou null pour les pauses indéfinies)
inventory_depleted — {} vide
disabled — {} vide

Événements de paiement

Événements liés aux paiements et aux virements.

Événement	Description
`payments.payout.created`	Déclenché lorsqu’un virement est envoyé sur votre compte bancaire
`bill.payment.created`	Déclenché lorsqu’un paiement d’addition est créé
`payment_link.created`	Déclenché lorsqu’un nouveau payment link est créé
`payment_link.paid`	Déclenché lorsqu’un paiement est encaissé avec succès via un payment link
`payment_link.refund.created`	Déclenché lorsqu’un remboursement est initié pour un paiement effectué via un payment link
`payment_link.refund.succeeded`	Déclenché lorsqu’un remboursement de payment link est confirmé comme réussi par la passerelle de paiement
`payment_link.refund.failed`	Déclenché lorsqu’un remboursement de payment link est rejeté par la passerelle de paiement

payments.payout.created

Déclenché lorsque storekit envoie un virement sur votre compte bancaire.

{
  "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 est une chaîne au format mois/année, ou une chaîne vide lorsque le fournisseur de paiement n’en a pas fourni.

payment_link.created

Déclenché lorsqu’un nouveau payment link est créé. Envoyé uniquement pour les comptes dont les webhooks sont activés.

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

Champ	Description
`paymentLink.id`	L’ID du payment link au format `plink_`
`paymentLink.type`	`one_off` ou `reusable`
`paymentLink.amountType`	`fixed` ou `variable`
`paymentLink.amount`	Montant fixe en unités monétaires mineures, ou `null` pour les liens à montant variable
`paymentLink.currency`	Code devise ISO 4217
`paymentLink.reference`	Votre référence interne, si définie
`venue.slug`	Le slug d’URL du magasin

payment_link.paid

Déclenché lorsqu’un paiement est encaissé avec succès via un payment link. Envoyé uniquement pour les comptes dont les webhooks sont activés.

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

Champ	Description
`paymentLink.id`	L’ID du payment link au format `plink_`
`paymentLink.type`	`one_off` ou `reusable`
`paymentLink.amountType`	`fixed` ou `variable`
`paymentLink.reference`	Votre référence interne, si définie
`payment.amount`	Montant encaissé en unités monétaires mineures (par ex. pence)
`payment.pspReference`	Référence de paiement Adyen
`venue.slug`	Le slug d’URL du magasin

payment_link.refund.created

Déclenché lorsqu’un remboursement est initié pour un paiement effectué via un payment link. Le remboursement est à ce stade en attente — la confirmation arrive via payment_link.refund.succeeded ou payment_link.refund.failed une fois que la passerelle de paiement l’a traité de manière asynchrone.

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

Champ	Description
`refund.id`	L’ID du remboursement
`refund.transactionId`	L’ID de transaction du paiement d’origine
`refund.amount`	Montant du remboursement en unités monétaires mineures (par ex. pence)
`refund.currency`	Code devise ISO 4217
`refund.reason`	Motif du remboursement, s’il a été fourni

payment_link.refund.succeeded

Déclenché lorsque la passerelle de paiement confirme qu’un remboursement a été traité avec succès. Cet événement se déclenche de manière asynchrone après 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

Déclenché lorsque la passerelle de paiement rejette un remboursement. Cet événement se déclenche de manière asynchrone après 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"
    }
  }
}

Événements d’imprimante

Événements liés au statut des imprimantes cloud.

Événement	Description
`printer.status.offline`	Déclenché lorsqu’une imprimante passe hors ligne
`printer.status.online`	Déclenché lorsqu’une imprimante revient en ligne

printer.status.offline

Déclenché lorsqu’une imprimante cloud connectée ne parvient plus à se signaler auprès du serveur storekit pendant 5 minutes. Une notification par e-mail est également envoyée à l’adresse configurée pour le magasin.

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

Une imprimante partagée par plusieurs magasins envoie un événement par magasin.

printer.status.online

Déclenché lorsqu’une imprimante cloud se reconnecte à nos serveurs après avoir été hors ligne pendant au moins 5 minutes. Une notification par e-mail est également envoyée pour confirmer que l’imprimante est de nouveau en ligne.

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

Événements webhook

Événements de commande

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

Événements de magasin

store.opened

store.closed

store.opening_hours.updated

Événements d’article

item.out_of_stock

Événements de paiement

payments.payout.created

payment_link.created

payment_link.paid

payment_link.refund.created

payment_link.refund.succeeded

payment_link.refund.failed

Événements d’imprimante

printer.status.offline

printer.status.online

​Événements de commande

​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

​Événements de magasin

​store.opened

​store.closed

​store.opening_hours.updated

​Événements d’article

​item.out_of_stock

​Événements de paiement

​payments.payout.created

​payment_link.created

​payment_link.paid

​payment_link.refund.created

​payment_link.refund.succeeded

​payment_link.refund.failed

​Événements d’imprimante

​printer.status.offline

​printer.status.online

Événements de commande

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

Événements de magasin

store.opened

store.closed

store.opening_hours.updated

Événements d’article

item.out_of_stock

Événements de paiement

payments.payout.created

payment_link.created

payment_link.paid

payment_link.refund.created

payment_link.refund.succeeded

payment_link.refund.failed

Événements d’imprimante

printer.status.offline

printer.status.online