> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create webhook subscription

> Subscribes a notification URL to event types.

POST`https://api.maple.inc/v1/webhook_subscriptions`API key

Subscribes a notification URL to event types. Returns the HMAC signing secret once.

## Authorization

Send your API key as `Authorization: Bearer <key>`: `mpk_test_…` against the sandbox (`https://api.staging.maple.inc/v1`), `mpk_live_…` against production. See [Authentication](https://docs.maple.inc/developer-api/concepts/authentication.md). The samples read the key from `MAPLE_KEY` and the base URL from `MAPLE_BASE`, as set up in the [Quickstart](https://docs.maple.inc/developer-api/quickstart.md).

## Request body

`application/json`, required.

- `notification_url` string required

- `event_types` string\[] required

## Responses

### 200 OK

- `object` string required

  Always `webhook_subscription.created`.

- `subscription` object required

- `subscription.object` string required

  Always `webhook_subscription`.

- `subscription.id` string required

- `subscription.environment` string required

  One of `test`, `live`.

- `subscription.notification_url` string required

- `subscription.event_types` string\[] required

- `subscription.status` string required

  One of `enabled`, `disabled`.

- `subscription.created_at` string required

- `subscription.updated_at` string required

- `signing_secret` string required

  One-time HMAC-SHA256 signing secret (`mwhsec_…`) used to verify webhook deliveries. Store it now; it is never shown again.

### Errors

- `400` Bad request DeveloperApiBadRequest

- `401` Unauthorized DeveloperApiUnauthorized

- `403` Forbidden DeveloperApiForbidden

- `429` Too many requests DeveloperApiRateLimited

Every error body names the error in `_tag`, explains it in `message`, and says where to report it in `feedback`. See [Errors](https://docs.maple.inc/developer-api/concepts/errors.md).

A `429` also sends `Retry-After`: Seconds to wait before retrying; also returned as retry\_after in the body.

Create webhook subscription

```sh
curl "$MAPLE_BASE/webhook_subscriptions" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification_url":"https://example.com/webhooks/maple","event_types":["order.notification"]}'
```

```python
import os
import requests


r = requests.post(
    f"{os.environ['MAPLE_BASE']}/webhook_subscriptions",
    headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"},
    json={
        "notification_url": "https://example.com/webhooks/maple",
        "event_types": [
            "order.notification",
        ],
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())
```

```js
const res = await fetch(`${process.env.MAPLE_BASE}/webhook_subscriptions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAPLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "notification_url": "https://example.com/webhooks/maple",
    "event_types": [
      "order.notification"
    ]
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

```json
{
  "object": "webhook_subscription.created",
  "subscription": {
    "object": "webhook_subscription",
    "id": "string",
    "environment": "test",
    "notification_url": "https://example.com/webhooks/maple",
    "event_types": [
      "order.notification"
    ],
    "status": "enabled",
    "created_at": "string",
    "updated_at": "string"
  },
  "signing_secret": "string"
}
```

```json
{
  "_tag": "DeveloperApiBadRequest",
  "code": "string",
  "message": "string",
  "feedback": "string"
}
```