Reference
Webhook topics
The webhook topics an app can subscribe to, the scope each requires, and the mandatory KVKK privacy topics.
This page is generated from the source code. Apps subscribe to topics in webhooks.subscriptions[].topics; each topic requires the scope listed in its scope column.
app
app/scopes_update
The app's granted scopes changed: the store approved a new version's scopes or an upgrade narrowed them.
- Scope needed
- None
app/uninstalled
The store uninstalled the app.
- Scope needed
- None
app_subscriptions
app_subscriptions/update
The status of one of the app's billing charges changed; sent only to that app.
- Scope needed
- None
checkouts
checkouts/update
A cart in checkout changed.
- Scope needed
read_orders
customers
customers/create
A customer was created via the admin, CSV import, first order, first sign-in or newsletter form. Payload is filtered by the app's customer data level, which must be at least 1.
- Scope needed
read_customers
customers/delete
A customer was deleted (including via KVKK erasure requests); payload contains only id.
- Scope needed
read_customers
customers/marketing_consent_update
A customer's marketing consent was granted or withdrawn anywhere (checkout, customer account, unsubscribe link, newsletter form, admin, CSV import, an app or IYS), a consenting customer requested erasure (state unsubscribed, source erasure_request; subsequent consent after an erasure request is reported the same way), or the store deleted them (state unsubscribed, source customer_deleted). Payload contains customer_id, channel, state, consent_updated_at and source; drop opted-out customers from your lists immediately. Requires read_marketing_audience or write_marketing_consent and customer data level 2.
- Scope needed
read_marketing_audience
Example body
{
"store_id": 1,
"customer_id": 42,
"channel": "email",
"state": "unsubscribed",
"consent_updated_at": "2026-11-12T08:30:00Z",
"source": "unsubscribe"
}customers/update
A customer's contact details, address, tags, marketing consent, order count or total spent changed. Payload is filtered by the app's customer data level.
- Scope needed
read_customers
draft_orders
draft_orders/create
A draft order was created.
- Scope needed
read_draft_orders
draft_orders/delete
A draft order was deleted; payload contains only id.
- Scope needed
read_draft_orders
draft_orders/update
A draft order was saved, invoiced or completed.
- Scope needed
read_draft_orders
fulfillments
fulfillments/create
A fulfillment was created for an order.
- Scope needed
read_orders
gift_cards
gift_cards/create
A gift card was created. Payload includes only the last four characters of the code.
- Scope needed
read_gift_cards
gift_cards/update
A gift card's balance, note, expiry date, customer or disabled state changed.
- Scope needed
read_gift_cards
inventory
inventory/low
A variant's stock dropped below its low-stock threshold.
- Scope needed
read_products
inventory_levels
inventory_levels/update
A stock quantity at a location changed; sent once per inventory record updated in an operation.
- Scope needed
read_inventory
iys
iys/consent
Marketing consents and opt-outs recorded by the store for filing with IYS (Turkey's commercial message registry); sent only to the selected SMS provider app when sms_commercial is enabled. The app reports each event's outcome in its response: recorded, rejected or retry.
- Scope needed
write_sms
Example body
{
"store_id": 1000000000001,
"events": [
{
"id": 7,
"channel": "email",
"recipient": "ayse@example.com",
"state": "granted",
"consent_at": "2026-11-12T08:30:00Z",
"source": "HS_WEB"
}
]
}orders
orders/cancelled
An order was cancelled.
- Scope needed
read_orders
orders/create
An order was created.
- Scope needed
read_orders
orders/paid
An order's payment completed.
- Scope needed
read_orders
orders/updated
An order changed: its status, line items, note, tags or addresses.
- Scope needed
read_orders
products
products/create
A product was added.
- Scope needed
read_products
products/delete
A product was deleted.
- Scope needed
read_products
products/update
A product changed.
- Scope needed
read_products
refunds
refunds/create
A refund was issued.
- Scope needed
read_orders
refunds/update
An app-initiated refund failed (for example, a card refund declined by the payment app). Successful refunds arrive via refunds/create.
- Scope needed
read_orders
shop
shop/update
The store's plan, name, contact details, language, currency, logo or primary domain (primary_url in the payload) changed. Payload matches GET /api/v1/shop with store_id added.
- Scope needed
- None
sms
sms/send
An SMS queued for the store's selected SMS provider app to send: recipient phone number and message text. The app reports the outcome via POST /api/v1/sms/{id}/status.
- Scope needed
write_sms
Example body
{
"id": 1000000000042,
"to": "+905xxxxxxxxx",
"body": "…",
"encoding": "gsm7",
"segments": 1,
"notification": "order_confirmation",
"order_id": 1000000001001,
"store_id": 1000000000001
}Mandatory KVKK topics
These topics do not use webhook subscriptions: every app must handle them at the endpoints configured in its privacy block (KVKK is Turkey's personal data protection law).
customers/data_request
A customer requested the personal data the app holds about them. Sent to privacy.customers_data_request_url.
customers/redact
A customer's personal data must be erased. Sent to privacy.customers_redact_url.
store/redact
All data held for a store that uninstalled the app must be erased. Sent to privacy.store_redact_url.