事件
內部事件參考
最後更新：2026年9月5日
STOAR 會在每一個重要的商務動作發生時發出領域事件——建立訂單、庫存不足、評論通過審核。這些事件就是平台的擴充介面：驅動對外 Webhook 的同一批訊號，在程序內也開放給自訂模組使用，因此自架或 SaaS 部署都能在不動到核心程式碼的前提下加上新行為。
每個事件都遵循 stoar.shop.<domain>.<action> 命名慣例，並帶有一份精簡的內容（相關的記錄，以及必要的上下文）。
從自訂模組監聽 #
自訂模組會在自己的 service provider 中註冊監聽器。事件觸發時，您的監聽器就會執行——排入一封電子郵件、同步到外部系統、寫入一筆稽核記錄，什麼都可以：
use Illuminate\Support\Facades\Event;
// In your module's ServiceProvider::boot()
Event::listen('stoar.shop.order.created', function ($order) {
// React to the new order.
});由於監聽器在程序內執行，它們看到的是即時的 model 記錄，並且可以在內建處理程式之前或同時採取行動。內建的低庫存記錄器、金流商與通知信件全都是這樣掛上去的——沒有任何東西是寫死的。
實體生命週期事件 #
核心記錄（商品、分類、顧客、折扣碼、地址）都從單一接縫發出 created、updated 與 deleted 事件，因此不論變更來自何處——後台、REST API、商店前台或背景工作——監聽器都能接到。像備份還原這類大量操作會刻意保持沉默，避免匯入期間灌爆監聽器。
事件參考 #
訂單
| 事件 | 觸發時機 |
|---|---|
order.created |
建立訂單（任何付款方式） |
order.completed |
訂單已付款 |
order.statusChanged |
訂單狀態變更 |
order.cancelled |
訂單已取消 |
order.refunded |
訂單已退款（全額或部分） |
order.paymentFailed |
付款失敗或工作階段逾期 |
order.disputeCreated |
開立退單爭議 |
order.offline_pending |
線下／手動訂單等待付款 |
order.bank_transfer_pending |
銀行轉帳訂單等待付款 |
顧客
| 事件 | 觸發時機 |
|---|---|
customer.created |
建立任何顧客記錄 |
customer.updated |
更新顧客記錄 |
customer.deleted |
刪除顧客 |
customer.registered |
購物者自行註冊（帶有驗證連結） |
customer.passwordReset |
要求重設密碼 |
customer.emailChangeRequested |
要求變更電子郵件地址 |
customer.wishlist.added |
商品被加入願望清單 |
customer.address.created / .updated / .deleted |
顧客地址有變動 |
商品與目錄
| 事件 | 觸發時機 |
|---|---|
product.created / .updated / .deleted |
商品有變動 |
category.created / .updated / .deleted |
分類有變動 |
評論
| 事件 | 觸發時機 |
|---|---|
review.submitted |
購物者送出評論 |
review.approved |
評論被設為可見 |
review.rejected |
評論被隱藏 |
review.deleted |
評論被刪除 |
庫存
| 事件 | 觸發時機 |
|---|---|
inventory.reserved |
結帳時保留庫存 |
inventory.released |
釋放一筆保留 |
inventory.adjusted |
庫存透過稽核調整記錄變動 |
inventory.low |
庫存降至低庫存門檻或以下 |
inventory.backInStock |
庫存回升到門檻之上 |
折扣碼與禮物卡
| 事件 | 觸發時機 |
|---|---|
coupon.created / .updated / .deleted |
折扣碼有變動 |
coupon.applied |
折扣碼套用到購物車 |
coupon.redeemed |
折扣碼的使用記錄到某筆訂單上 |
giftcard.issued |
發行禮物卡 |
giftcard.redeemed |
從禮物卡兌用一筆金額 |
訂閱
| 事件 | 觸發時機 |
|---|---|
subscription.created |
建立訂閱 |
subscription.cancelled |
取消訂閱 |
subscription.paymentFailed |
續訂扣款失敗 |
其他
| 事件 | 觸發時機 |
|---|---|
newsletter.subscribed |
有人訂閱電子報 |
contact.submitted |
送出聯絡表單 |
訂閱時，上述每個名稱前面都要加上
stoar.shop.前綴——例如stoar.shop.inventory.low。
事件與 Webhook 的差別 #
兩者由相同的訊號驅動。當外部系統需要透過 HTTP 收到通知時，請使用 Webhook；當自訂模組需要在商店內部執行邏輯時，請使用事件監聽器。