Skip to content
biticaretdevelopers

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.

toml
[[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

http
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 one v1 signature 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=value lines (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 2xx status within 5 seconds marks the delivery successful (25 seconds for store/redact, 20 seconds 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 2xx resets 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:

http
GET /api/v1/webhook_deliveries
POST /api/v1/webhook_deliveries/{id}/replay

Logs 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.

toml
[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.

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.

json
{ "store_id": 1, "customer_id": 42, "channel": "email", "state": "unsubscribed", "consent_updated_at": "2026-11-12T08:30:00Z", "source": "unsubscribe" }
  • channel is email or sms. Each channel's consent is independent and reported separately.
  • state is subscribed or unsubscribed. A customer erasure request emits unsubscribed with source erasure_request; if a merchant deletes a consenting customer, it emits unsubscribed with source customer_deleted.
  • Remove a customer from your active mailing or SMS list as soon as unsubscribed arrives.

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.

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

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" } ] }
  • state is granted or withdrawn.
  • source is the IYS source code (HS_WEB, HS_FIZIKSEL_ORTAM, HS_EORTAM).
  • channel is email or sms. recipient is the email address, or for SMS the consented mobile number (E.164, +905…).

Unlike other topics, the platform processes your HTTP response body:

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