---
url: https://docs.youcan.shop/store-admin/resthooks/subscribe.md
---
# 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](/store-admin/resthooks/overview#available-events). Use the canonical names, the legacy aliases are deprecated. | yes |

## Example Request

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

## Responses

\[200] Ok

```json
{
  "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](/store-admin/resthooks/overview#delivery-and-retries), subscribing activates it again and resets its failure count.

\[429] Too Many Requests

```json
{
  "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](/store-admin/resthooks/list) your subscriptions and [unsubscribe](/store-admin/resthooks/unsubscribe) from unused ones.

\[401] Unauthorized

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

> Solution: Check your [access token](/store-admin/introduction/oauth) is valid and ensure you've allowed the `edit-rest-hooks` scope.

## Deliveries

Every delivery wraps the event object in the standard [payload format](/store-admin/resthooks/overview#payload-format) and carries the [delivery headers](/store-admin/resthooks/overview#delivery-headers). Verify the [signature](/store-admin/resthooks/overview#youcan-signature), respond with a `2xx` quickly, and read the [retry policy](/store-admin/resthooks/overview#delivery-and-retries) 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](/apps/webhooks).