---
title: "Create a webhook subscription"
method: POST
path: "/webhooks/subscriptions"
---

# Create a webhook subscription

`POST /webhooks/subscriptions`

Subscribe a public HTTPS URL to one or more platform events. Every requested event is delivered to the same URL and signed with the single `signingSecret` returned in the response — store it, as it is only returned at creation time. The token must hold the OAuth scope each requested event needs: `read:creator` for `subscription.new`, `subscription.renewed`, `subscription.cancelled`, `subscription.expired`, `follow.new`, `purchase.new`, `tip.new`, the `checkout_link.*` and `payout.paid` events, and the `creator.payment.succeeded`, `creator.subscription.*`, `creator.refund.created`, and `creator.dispute.*` events; `read:post` for `creator.post.liked` and `creator.post.commented`; `read:chat` for `message.received`, `message.read`, `creator.message.received`, `creator.message.sent`, `creator.message.read`, `creator.message.reaction`, and `creator.message.deleted`.

## Headers

- `X-Fanvue-API-Version` string, required

## Request body

- object
  - `url` string, uri, required — Public HTTPS URL the event payloads are delivered to (no redirects, no localhost)
  - `events` string[], required — One or more platform events this subscription delivers

## Response `201`

Webhook subscription created successfully

- object
  - `id` string, uuid, required — ID of the created webhook subscription
  - `signingSecret` string, required — HMAC signing secret for verifying delivery signatures. Returned only on creation — store it securely now.

## Other responses

- `400` — Bad Request - API version not supported OR validation failed
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `410` — API version no longer supported (sunset)
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.net/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.net/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/c5ddcd5c7e72/schema)