.dev

Appearance

Webhooks ​

Webhooks notify your app when something happens in a store: an order is created, a charge changes, a seller uninstalls your app. YouCan sends a POST request with a JSON payload to an address you choose.

See the REST Hooks reference for the list of events, the payload format, signature verification, and the retry policy.

Declare subscriptions in your app config ​

Declare your subscriptions in youcan.app.json. They deploy with your app version and apply to every store that installs your app.

json
{
  "name": "my-app",
  "app_url": "https://myapp.example.com",
  "webhooks": [
    { "topic": "order.created", "address": "/webhooks/order.created" },
    { "topic": "app.uninstalled", "address": "/webhooks/app.uninstalled" }
  ]
}
  • topic is one of the available events.
  • address is where the event is delivered. A relative address resolves against your app_url. An absolute address must use https.
  • You can declare up to 20 webhooks, and your app holds at most 7 active subscriptions per topic per store.

Use relative addresses. One declaration then works in every environment:

  • During youcan app dev, your development store subscribes to your declared topics, and the addresses resolve to your tunnel. Your local server receives the events. The subscriptions are removed when the dev session ends.
  • When you run youcan app deploy, the release applies your declaration to every installed store, and the addresses resolve to your released app_url. New installs subscribe automatically. A release also activates again any subscription that was deactivated after delivery failures.

Receive a delivery ​

Verify the signature, respond with a 2xx status code quickly, and do the work after. The app template ships a working receiver at server/routes/webhooks/[event].post.ts.

Subscribe at runtime ​

Your app can also manage subscriptions per store through the REST Hooks API, for cases the static declaration does not cover.

Monitor deliveries ​

Open your app in the Partners dashboard and go to the Webhooks tab. It shows the success rate, the delivery volume over time, and the average latency for the last 24 hours or 30 days.

Each delivery lists its topic, address, outcome, HTTP status, attempts, and duration. Open a delivery to inspect the exact payload we sent and the response your endpoint returned. The Redeliver button sends the same payload again with the same delivery id, use it after you fix a bug in your receiver.

The Subscriptions view lists every subscription of your app across all stores, with its status, consecutive failure count, and last delivery. Search by store slug or id, and filter by status.

Deliveries are kept for 30 days.

Failures and deactivation ​

Failed deliveries follow the retry policy: server errors retry up to 5 times over approximately 4 hours, client errors do not retry.

A subscription is deactivated when your endpoint answers 410 Gone, or after 1000 consecutive failed deliveries. A successful delivery resets the counter. We email your organization when that happens (at most once per day per app), and the store stops receiving that topic at that address.

To restore a deactivated subscription, make sure the endpoint accepts deliveries again, then reactivate it from the Subscriptions view in the Webhooks tab. Releasing a version of your app also reactivates its declared webhooks, and subscriptions created through the REST Hooks API can be restored by subscribing to the same topic and address again.

© 2022-2026 YouCan