> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WebhookSubscriptions

> `composio.webhooks.subscriptions` — the project's outbound webhook subscription. The API allows one subscription per project; every response includes the signing `secret` used to verify deliveries with `composio.triggers.verifyWebhook()` / `composio.triggers.parse()`.

## Usage

Access this class through the `composio.webhookSubscriptions` property:

```typescript theme={null}
const composio = new Composio({ apiKey: 'your-api-key' });
const result = await composio.webhookSubscriptions.list();
```

## Methods

### delete()

Delete a webhook subscription. Deliveries stop immediately.

```typescript theme={null}
async delete(id: string, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscriptionDeleteResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | The subscription id |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscriptionDeleteResponse>` — `\{ success \}`

**Example**

```typescript theme={null}
await composio.webhooks.subscriptions.delete('whs_abc123');
```

***

### get()

Retrieve a webhook subscription by id.

```typescript theme={null}
async get(id: string, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | The subscription id |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscription>` — The subscription, including its signing secret

**Example**

```typescript theme={null}
const subscription = await composio.webhooks.subscriptions.get('whs_abc123');
console.log(subscription.enabledEvents);
```

***

### list()

List the project's webhook subscriptions.

```typescript theme={null}
async list(query?: WebhookSubscriptionListParams, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscriptionListResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `query?` | `WebhookSubscriptionListParams` | Pagination options |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscriptionListResponse>` — Paginated subscriptions

**Example**

```typescript theme={null}
const { items } = await composio.webhooks.subscriptions.list();
console.log(items[0]?.webhookUrl);
```

***

### listEventTypes()

List the event types a subscription can enable, with the payload versions each one supports.

```typescript theme={null}
async listEventTypes(requestOptions?: ComposioRequestOptions): Promise<WebhookSubscriptionEventTypesResponse>
```

**Parameters**

| Name | Type |
| - | - |
| `requestOptions?` | `ComposioRequestOptions` |

**Returns**

`Promise<WebhookSubscriptionEventTypesResponse>` — The available event types

**Example**

```typescript theme={null}
const { items } = await composio.webhooks.subscriptions.listEventTypes();
console.log(items.map(item => item.eventType));
```

***

### rotateSecret()

Rotate the signing secret of a webhook subscription. The previous secret stops validating, so update your verifier with the returned `secret`.

```typescript theme={null}
async rotateSecret(id: string, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscriptionRotateSecretResponse>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | The subscription id |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscriptionRotateSecretResponse>` — `\{ id, secret \}`

**Example**

```typescript theme={null}
const { secret } = await composio.webhooks.subscriptions.rotateSecret('whs_abc123');
```

***

### set()

Create or update the project webhook subscription.

If a subscription already exists it is updated in place, otherwise a new one is created. By default this subscribes to V3 trigger message events.

```typescript theme={null}
async set(params: WebhookSubscriptionSetParams, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `params` | `WebhookSubscriptionSetParams` | `webhookUrl`, optional `enabledEvents` and `version` |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscription>` — The resulting subscription

**Example**

```typescript theme={null}
const subscription = await composio.webhooks.subscriptions.set({
  webhookUrl: `${APP_URL}/webhooks/composio`,
  enabledEvents: ['composio.trigger.message', 'composio.connected_account.expired'],
});
process.env.COMPOSIO_WEBHOOK_SECRET = subscription.secret;
```

***

### update()

Update an existing webhook subscription. Only the provided fields change.

```typescript theme={null}
async update(id: string, params: WebhookSubscriptionUpdateParams, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | The subscription id |
| `params` | `WebhookSubscriptionUpdateParams` | Fields to update |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<WebhookSubscription>` — The updated subscription

**Example**

```typescript theme={null}
await composio.webhooks.subscriptions.update('whs_abc123', {
  enabledEvents: ['composio.trigger.message'],
});
```

***
