---
search:
  tags:
    - Webhooks
    - POST
seo:
  description: >-
    Creates a new webhook subscription. After creation the API sends a…
    Reference for the POST /hub/{shop_id}/subscriptions endpoint in the Bolder
    API v1.
sidebar:
  label: Subscribe
  badge: POST
title: Subscribe
type: openapi-operation
---
Creates a new webhook subscription. After creation the API sends a verification POST to
your `url` containing a `X-Hook-Ping` header. Your endpoint must respond with a matching
`X-Hook-Pong` header to activate the subscription.

#### Subscription states

| Status | Description |
|--------|-------------|
| `pending` | Created, awaiting verification |
| `active` | Verified and receiving events |
| `failed_activation` | Verification was rejected |
| `failed` | Disabled after 3 consecutive delivery failures |
| `disabled` | Manually disabled or target returned `410` |

#### Available event topics

**Orders:** `orders`, `orders.created`, `orders.created.checkout`, `orders.updated`,
`orders.updated.placed`, `orders.updated.closed`, `orders.updated.shipped`,
`orders.updated.cancelled`, `orders.deleted`

**Products:** `products`, `products.created`, `products.updated`, `products.deleted`,
`products.updated.variants.created`, `products.updated.variants.updated`,
`products.updated.variants.deleted`, `products.updated.assets.created`,
`products.updated.assets.deleted`

`POST /hub/{shop_id}/subscriptions`

**Request body** (`application/json`, required)

- `topic` (string, required) — Event topic to subscribe to, e.g. \`orders.updated.placed\`
- `url` (string, required) — URL to POST event notifications to
- `notify_origin` (boolean) — Whether to notify the originating app
- `auth` (SubscriptionAuth)

Request body example:

```json
{
  "topic": "orders.updated.placed",
  "url": "https://www.myapp.com/events",
  "notify_origin": true,
  "auth": {
    "type": "basic",
    "username": "foo",
    "password": "bar"
  }
}
```

**Responses**

- `201` — Subscription created (pending verification)
- `422` — Validation errors

Response example, 201:

```json
{
  "id": 0,
  "status": "pending",
  "topic": "string",
  "url": "string",
  "notify_origin": true,
  "auth": {
    "type": "none",
    "username": "string",
    "password": "string"
  },
  "error_count": 0,
  "last_error": "string",
  "created_on": "2019-08-24T14:15:22Z",
  "updated_on": "2019-08-24T14:15:22Z",
  "_links": {}
}
```

Response example, 422:

```json
{
  "_class": [
    "errors"
  ],
  "_embedded": {
    "errors": [
      {
        "_class": [
          "error"
        ],
        "field": "product.title",
        "messages": [
          "can't be blank"
        ]
      }
    ]
  }
}
```