Skip to content
biticaretdevelopers

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

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

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

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

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

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