# Create a subscription

Subscribes to topics at an endpoint registered in the version, and returns the signing secret once.

```http
POST https://larm.sa/stores/{storeId}/v1/webhook-subscriptions
```

One subscription per installation. Each topic requires its scope. See [Webhooks](/guides/webhooks) for details.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `endpoint_url` | string (uri) | yes |  |
| `event_types` | array<string> | yes |  |
| `payload_version` | object | yes |  |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.id` | string (uuid) | no |  |
| `data.endpoint_url` | string (uri) | no |  |
| `data.event_types` | array<string> | no |  |
| `data.payload_version` | object | no |  |
| `data.state` | object | no | One of: `active`, `paused`, `revoked`. |
| `data.secret_generation` | integer | no |  |
| `data.issued_scopes` | array<string> | no |  |
| `execution` | object | no | Who executed the request: the app, version, installation and store. Field names here are camelCase. |
| `execution.appId` | string (uuid) | no |  |
| `execution.versionId` | string (uuid) | no |  |
| `execution.installationId` | string (uuid) | no |  |
| `execution.storeId` | string (uuid) | no |  |
| `execution.requestId` | string (uuid) | no |  |
| `execution.generation` | integer | no |  |
| `execution.routeEpoch` | integer | no |  |
| `execution.appAuthEpoch` | integer | no |  |
| `execution.grantRevision` | integer | no |  |
| `meta` | object | yes |  |
| `meta.request_id` | string (uuid) | no | The request ID; include it in any support request. |
| `secret` | string | no | Signing secret: 32 bytes, base64url-encoded. Returned once. |


## Example request

```bash
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint_url": "https://app.example.com/larm/webhooks", "event_types": [ "order.created", "order.paid" ], "payload_version": 1 }'
```


## Example response (200)

```json
{
  "data": {
    "id": "8d1f0c2a-4b3e-4a5f-9c6d-7e8f9a0b1c2d",
    "endpoint_url": "https://app.example.com/larm/webhooks",
    "event_types": [
      "order.created",
      "order.paid"
    ],
    "payload_version": 1,
    "state": "active",
    "secret_generation": 1,
    "issued_scopes": [
      "orders:read"
    ]
  },
  "execution": {
    "appId": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
    "versionId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "installationId": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d",
    "storeId": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10",
    "requestId": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a",
    "generation": 1,
    "routeEpoch": 4,
    "appAuthEpoch": 1,
    "grantRevision": 2
  },
  "meta": {
    "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a"
  },
  "secret": "q3V0bWx…base64url…"
}
```


## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 409 | `SUBSCRIPTION_EXISTS` | The installation already has a subscription. |
| 403 | `ENDPOINT_NOT_APPROVED` | The URL is not registered in the version. |
| 422 | `ENDPOINT_UNSAFE` | The URL is not a public https URL. |
| 403 | `SCOPE_REQUIRED` | A topic without its scope. |