Subscribe to event

Endpoint: https://api.youcan.shop/resthooks/subscribe

Method: POST

Required Scopes

• edit-rest-hooks

Request Body

Param Name	Param Type	Description	Required
target_url	string	The URL we POST to when the event occurs. Must be https and publicly accessible, localhost and private network URLs do not work.	yes
event	string	One of the available events. Use the canonical names, the legacy aliases are deprecated.	yes

Example Request

{
  "event": "order.created",
  "target_url": "https://yourdomain.com/webhooks/order.created"
}

Responses

[200] Ok

{
  "id": "8e6b019b-06de-496d-a96d-c9ee69c0ccf0"
}

Subscribing to an event and address that already has a subscription returns the existing subscription's id instead of creating a duplicate. When that subscription was deactivated, subscribing activates it again and resets its failure count.

[429] Too Many Requests

{
  "status": 429,
  "detail": "This store has reached the max of subscriptions for this event.",
  "meta": []
}

Solution: each app (OAuth client) holds at most 7 active subscriptions per event per store. Deactivated subscriptions do not count. List your subscriptions and unsubscribe from unused ones.

[401] Unauthorized

{
  "status": 401,
  "detail": "Unauthenticated",
  "meta": []
}

Solution: Check your access token is valid and ensure you've allowed the edit-rest-hooks scope.

Deliveries

Every delivery wraps the event object in the standard payload format and carries the delivery headers. Verify the signature, respond with a 2xx quickly, and read the retry policy to understand what happens when your endpoint fails.

Apps can also declare their subscriptions in youcan.app.json instead of calling this endpoint per store, see app webhooks.