Apps
Webhooks
Subscribe to webhooks, verify their signature, handle retries, answer the privacy topics, and use the topics with their own bodies (shop/update, customers, marketing consent, SMS and IYS).
When an event occurs in a store, the platform sends an HTTP POST request to your app's webhook endpoint. This page covers subscribing to topics, verifying signatures, delivery and retries, and topics with special payload rules. All topics and their required scopes: Webhook topics.
Subscribe to topics
Webhook subscriptions live in biticaret.app.toml and are registered upon installation. Each OAuth code exchange updates the installation's subscriptions to match the installed version.
[[webhooks.subscriptions]]
topics = ["app/uninstalled"]
uri = "/webhooks/app-uninstalled"A topic is delivered only to installations granted its required scope, and every configured topic's scope must be declared in access_scopes. Webhook URIs must use HTTPS. An app may have at most 50 subscriptions.
What a delivery looks like
POST /webhooks/orders-paid HTTP/1.1
Content-Type: application/json
x-biticaret-topic: orders/paid
x-biticaret-store-id: 1000000000001
x-biticaret-store-domain: acme.localhost
x-biticaret-event-id: 01929f8a-7c10-…
x-biticaret-triggered-at: 2026-10-18T10:00:00Z
x-biticaret-api-version: 2026-10
x-biticaret-signature: t=1792317600,v1=…x-biticaret-event-id uniquely identifies the event across all matching subscriptions, retries and replays. Because the same event can be delivered more than once, your webhook handler should be idempotent.
Look up the store using store_id in the payload (or x-biticaret-store-id), as a store's domain can change.
Verify the signature
Every webhook delivery carries one signature header, and a delivery without it must be refused:
-
x-biticaret-signature: t=<unix seconds of this attempt>,v1=<base64 HMAC-SHA256>: covers both headers and body. While rotating secrets, it carries onev1signature per active secret. It is computed over these exact bytes:t=<t> event_id=<x-biticaret-event-id> topic=<x-biticaret-topic> store_domain=<x-biticaret-store-domain> triggered_at=<x-biticaret-triggered-at> api_version=<x-biticaret-api-version> <raw body>That is six
name=valuelines (each terminated by\n), followed by an empty line, followed by the raw request body.
Verify this signature. Because it binds both the topic and the store, a captured orders/paid request cannot be replayed against another endpoint. Reject any t more than 5 minutes from the current time. Any v1 matching one of your active secrets is valid. An endpoint dedicated to a single topic should also reject requests whose signed topic does not match with 401, just as it rejects an invalid signature.
In Go, the Go template handles all of this automatically.
Delivery and retries
- Returning a
2xxstatus within 5 seconds marks the delivery successful (25seconds for store/redact,20seconds for iys/consent). Queue heavy work asynchronously and respond immediately. - Otherwise the platform retries up to 8 attempts in total over roughly 4 hours, waiting 1, 5, 10 and 30 minutes, then 1 hour, 1 hour and 75 minutes between attempts. After the eighth failed attempt, the delivery is marked failed.
- Circuit breaker. After 10 consecutive failed deliveries, the subscription is paused for 15 minutes. No deliveries are attempted during the pause; queued events are delivered once it ends without consuming retry attempts. The first
2xxresets the failure counter. - When an app is uninstalled, pending deliveries are marked failed, while app/uninstalled is still sent.
Read the delivery log and replay a delivery
An app can inspect its webhook delivery log and replay failed or past deliveries:
GET /api/v1/webhook_deliveries
POST /api/v1/webhook_deliveries/{id}/replayLogs retain each delivery's status (pending, delivered, failed), attempt count, HTTP status code and duration for 30 days. Request bodies are retained for 7 days, allowing replays within that window. A replay creates a new delivery with the original x-biticaret-event-id.
Answer the privacy topics
Every app must serve three privacy endpoints. These are not webhook subscriptions: configure them under [privacy]—they require no scopes.
[privacy]
customers_data_request_url = "/privacy/customers-data-request"
customers_redact_url = "/privacy/customers-redact"
store_redact_url = "/privacy/store-redact"| Topic | Purpose |
|---|---|
customers/data_request |
Report the personal data you store for a customer. |
customers/redact |
Erase the personal data you store for a customer. |
store/redact |
Erase all data you store for a store. |
store/redact is sent 30 days after the app is uninstalled, and only to that app. Do not delete the store's data immediately on app/uninstalled: if the merchant reinstalls within 30 days, the scheduled store/redact is cancelled and expects existing data to remain intact. Because uninstalling revokes the access token, the handler must not depend on calling the store API and must be idempotent. Its body is {store_domain, store_id}; identify the store by store_id.
During that 30-day window, customers/redact also continues to reach the uninstalled app.
shop/update
shop/update requires no scope and is delivered to every installed app subscribed to it. It fires when the store's plan, name, contact details, language, currency, logo or primary domain changes. Its payload is the GET /api/v1/shop response with store_id added. After a domain change, primary_url holds the new address.
Use primary_url when constructing buyer-facing links (such as product feed URLs or links in emails) and update them whenever this webhook arrives.
customers/marketing_consent_update
This topic is intended for marketing apps and requires read_marketing_audience or write_marketing_consent along with customer data level 2. It fires whenever a customer's email or SMS marketing consent is granted or withdrawn anywhere (checkout, customer account, unsubscribe link, newsletter form, admin, CSV import, an app or IYS), and when a consenting customer requests data erasure. It is queued inside the same database transaction as the change, so a rolled-back update emits nothing.
{ "store_id": 1, "customer_id": 42, "channel": "email", "state": "unsubscribed", "consent_updated_at": "2026-11-12T08:30:00Z", "source": "unsubscribe" }channelisemailorsms. Each channel's consent is independent and reported separately.stateissubscribedorunsubscribed. A customer erasure request emitsunsubscribedwithsourceerasure_request; if a merchant deletes a consenting customer, it emitsunsubscribedwithsourcecustomer_deleted.- Remove a customer from your active mailing or SMS list as soon as
unsubscribedarrives.
customers/create, customers/update, customers/delete
These topics require read_customers and customer data level 1 or higher; configurations at level 0 requesting them are rejected. Each database transaction emits at most one notification per customer—a customer created and updated in the same transaction triggers only customers/create.
The payload of customers/create and customers/update matches GET /api/v1/customers/{id}, filtered by the app's customer data level. At level 1 you receive id, tags, accepts_marketing, orders_count, total_spent_cents and timestamps, while contact fields are null. customers/delete carries only id and fires for customers deleted via privacy erasure requests as well.
sms/send
This topic is delivered only to the app selected by the store as its SMS provider (sms_provider = true and write_sms); subscribing alone is not sufficient. One webhook is sent per SMS. Retries behave like all other webhooks, so the same SMS can arrive more than once—deduplicate by id.
{ "id": 1000000000042, "to": "+905xxxxxxxxx", "body": "…", "encoding": "gsm7", "segments": 1, "notification": "order_confirmation", "order_id": 1000000001001, "store_id": 1000000000001 }encoding is gsm7 or ucs2, and segments is the segment count calculated by the platform. notification identifies the platform notification (such as order_confirmation or shipping_confirmation), or is empty for an SMS initiated by an app via POST /api/v1/sms. Report delivery status via POST /api/v1/sms/{id}/status (App API).
iys/consent
IYS (İleti Yönetim Sistemi) is Turkey's national registry for commercial electronic message consents. This topic is delivered only to the store's selected SMS provider app, and only when the installed version declares sms_commercial = true; subscribing is otherwise disallowed. Every 10 minutes, the platform sends newly recorded marketing consents and opt-outs in batches of up to 100 events. The app files them in IYS under the merchant's brand.
{ "store_id": 1000000000001, "events": [ { "id": 7, "channel": "email", "recipient": "ayse@example.com", "state": "granted", "consent_at": "2026-11-12T08:30:00Z", "source": "HS_WEB" } ] }stateisgrantedorwithdrawn.sourceis the IYS source code (HS_WEB,HS_FIZIKSEL_ORTAM,HS_EORTAM).channelisemailorsms.recipientis the email address, or for SMS the consented mobile number (E.164,+905…).
Unlike other topics, the platform processes your HTTP response body:
{ "results": [ { "id": 7, "status": "recorded" } ] }status is recorded (done), rejected (IYS refused it; error explains why) or retry (requeued for the next batch). The app writes opt-outs originating in IYS back to the store via POST /api/v1/customers/{id}/marketing_consent with "source": "iys".