# 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](../reference/webhook-topics.md).

## 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](https://github.com/biticaret/app-template-go) 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.

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

```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](api.md#sms)).

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

```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"`.
