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.

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

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 when deliveries keep failing. We email your organization when that happens, and the store stops receiving that topic at that address.

To restore a deactivated subscription, make sure the endpoint accepts deliveries again, then release a version of your app with youcan app deploy or from your Partners dashboard. For subscriptions created through the REST Hooks API, subscribe to the same topic and address again instead.