# Webhooks

> How a shop tells your app what happened, and what your app should answer.

Source: https://storeware.ai/docs/webhooks

## Subscribing

Name the topics you want in your manifest, and the URL they are posted to:

```toml title="storeware.app.toml"
[oauth]
scopes = ["orders:read"]

[webhooks]
url = "https://yourapp.example/webhooks"
events = ["order.paid.v1", "order.refunded.v1"]
```

Every topic needs a scope that reads the same data, because an event is a read: `order.created.v1` carries the buyer's email address. The [event reference](https://storeware.ai/docs/webhooks/events) lists every topic and the scopes that cover it. An installation is only ever sent the events its grant covers.

## Answering

- Answer 2xx within ten seconds. Anything else, a redirect included, is a failure, retried six times over about nine hours.
- Answer 401 to a signature that does not verify, so a misconfiguration shows in the merchant's delivery log. See [Verifying requests](https://storeware.ai/docs/webhooks/verifying).
- Answer topics you do not handle with a 200, not an error.
- Delivery is at least once and in no promised order. Key your work on the event, and read current state rather than adding up changes. See [Payloads and delivery](https://storeware.ai/docs/webhooks/delivery).

## Events about your app

`app.installed.v1`, `app.uninstalled.v1`, `app.scopes_changed.v1`, `app.release_approved.v1` and `app.settings_updated.v1` go to your webhook URL whether or not you subscribe, and only to you. `app.uninstalled.v1` arrives after the uninstall, when your tokens no longer work. The billing topics arrive the same way: see [Charging merchants](https://storeware.ai/docs/selling/billing). For `app.settings_updated.v1`, see [Settings](https://storeware.ai/docs/extensions/settings).

`compliance.customer_data_requested.v1`, `compliance.customer_redacted.v1` and `compliance.store_redacted.v1` go to your `[privacy] url`. Act on them: they are how a shop meets its customers' rights. The merchant answers the request itself, so your app's token cannot export or erase a customer's data.

## Trying one

> **Early access.** The CLI and the SDK are not on npm yet, so the commands below do not run for everyone. To build an app now, write to https://storeware.ai/contact.

```bash
npx @storeware/cli webhook trigger order.paid.v1
```

Sends your app the latest real event of that topic from your development stores, signed as a delivery is.