---
title: "Create webhook subscription"
method: POST
path: "/api/v3.1/webhook_subscriptions"
tags: ["Webhook Subscriptions"]
---

# Create webhook subscription

`POST /api/v3.1/webhook_subscriptions`

Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned in subscription responses.

## Request body

- object
  - `webhook_url` string, uri, required — HTTPS URL to receive webhook events
  - `enabled_events` string[], required — Array of event types to subscribe to
  - `version` 'V1' | 'V2' | 'V3' — Webhook payload version

## Response `201`

Webhook subscription created

- object
  - `id` string, webhookSubscriptionId, required — Unique subscription ID
  - `webhook_url` string, required — Webhook destination URL
  - `version` 'V1' | 'V2' | 'V3', required — Webhook payload version
  - `enabled_events` string[], required — Subscribed event types
  - `secret` string, required — Signing secret for HMAC verification
  - `created_at` string, required — ISO 8601 timestamp
  - `updated_at` string, required — ISO 8601 timestamp

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `409` — Subscription already exists
- `500` — Internal server error

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/versions/4239836857f8/schema)