[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / WebhookManager

# Class: WebhookManager

Webhook Manager - Clean, high-level interface for webhook operations

Webhooks enable integration with external systems (n8n, Zapier, custom backends):

- **Admin operations**: Create, configure, and manage webhook endpoints
- **Trigger operations**: Programmatically trigger webhooks with payloads
- **Async workflows**: Wait for callbacks from workflow systems
- **Monitoring**: Track execution history


## Security Model

- Admin endpoints require tenant authentication
- Trigger endpoints work with user/business/tenant auth
- Caller identity is passed to webhook target


**`Example`**

```typescript
// Admin: Create a webhook for order processing
const webhook = await sdk.webhooks.create({
  name: 'Process Order',
  targetUrl: 'https://n8n.example.com/webhook/orders',
  method: 'POST',
  headers: { 'X-Custom-Header': 'value' }
});

// Trigger webhook with order data
const result = await sdk.webhooks.trigger(webhook.id, {
  orderId: 'order-123',
  items: [{ productId: 'prod-1', quantity: 2 }]
});

console.log('Execution ID:', result.executionId);
```

**`Example`**

```typescript
// Trigger and wait for workflow completion (up to 30s)
const result = await sdk.webhooks.triggerAndWait(
  'ai-processing-webhook',
  { prompt: 'Generate report for Q1' },
  30000
);

if (result.status === 'COMPLETED') {
  console.log('AI Response:', result.body);
}
```

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/webhookmanager#constructor)


### Methods

- [getAll](/sdk-reference/classes/webhookmanager#getall)
- [getActive](/sdk-reference/classes/webhookmanager#getactive)
- [getById](/sdk-reference/classes/webhookmanager#getbyid)
- [create](/sdk-reference/classes/webhookmanager#create)
- [update](/sdk-reference/classes/webhookmanager#update)
- [enable](/sdk-reference/classes/webhookmanager#enable)
- [disable](/sdk-reference/classes/webhookmanager#disable)
- [delete](/sdk-reference/classes/webhookmanager#delete)
- [get](/sdk-reference/classes/webhookmanager#get)
- [trigger](/sdk-reference/classes/webhookmanager#trigger)
- [triggerAndWait](/sdk-reference/classes/webhookmanager#triggerandwait)
- [getExecutions](/sdk-reference/classes/webhookmanager#getexecutions)
- [getExecutionById](/sdk-reference/classes/webhookmanager#getexecutionbyid)
- [getWebhookService](/sdk-reference/classes/webhookmanager#getwebhookservice)


## Constructors

### constructor

• **new WebhookManager**(`apiClient`, `projectKey`, `events?`): [`WebhookManager`](/sdk-reference/classes/webhookmanager)

#### Parameters

| Name | Type |
|  --- | --- |
| `apiClient` | [`PersApiClient`](/sdk-reference/classes/persapiclient) |
| `projectKey` | `string` |
| `events?` | [`PersEventEmitter`](/sdk-reference/classes/perseventemitter) |


#### Returns

[`WebhookManager`](/sdk-reference/classes/webhookmanager)

#### Defined in

[managers/webhook-manager.ts:71](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L71)

## Methods

### getAll

▸ **getAll**(`options?`): `Promise`<`PaginatedResponseDTO`<`WebhookDTO`>>

Get all webhooks with optional filters (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | [`WebhookQueryOptions`](/sdk-reference/interfaces/webhookqueryoptions) | Filter and pagination options |


#### Returns

`Promise`<`PaginatedResponseDTO`<`WebhookDTO`>>

Promise resolving to paginated webhooks

**`Example`**

```typescript
// Get all webhooks
const webhooks = await sdk.webhooks.getAll();

// Get only active webhooks
const active = await sdk.webhooks.getAll({ active: true });

// Search by name
const found = await sdk.webhooks.getAll({ search: 'order' });
```

#### Defined in

[managers/webhook-manager.ts:102](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L102)

### getActive

▸ **getActive**(): `Promise`<`PaginatedResponseDTO`<`WebhookDTO`>>

Get active webhooks only (Admin)

#### Returns

`Promise`<`PaginatedResponseDTO`<`WebhookDTO`>>

#### Defined in

[managers/webhook-manager.ts:109](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L109)

### getById

▸ **getById**(`webhookId`): `Promise`<`WebhookDTO`>

Get webhook by ID (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `webhookId` | `string` | UUID of the webhook |


#### Returns

`Promise`<`WebhookDTO`>

Promise resolving to webhook details

#### Defined in

[managers/webhook-manager.ts:119](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L119)

### create

▸ **create**(`webhook`): `Promise`<`WebhookDTO`>

Create a new webhook (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `webhook` | `WebhookCreateRequestDTO` | Webhook configuration |


#### Returns

`Promise`<`WebhookDTO`>

Promise resolving to created webhook

**`Example`**

```typescript
const webhook = await sdk.webhooks.create({
  name: 'Order Notifications',
  targetUrl: 'https://api.example.com/webhooks/orders',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer secret-token'
  },
  rateLimitPerMinute: 60
});
```

#### Defined in

[managers/webhook-manager.ts:142](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L142)

### update

▸ **update**(`webhookId`, `webhook`): `Promise`<`WebhookDTO`>

Update a webhook (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `webhookId` | `string` | UUID of the webhook to update |
| `webhook` | `WebhookUpdateRequestDTO` | Updated configuration (partial) |


#### Returns

`Promise`<`WebhookDTO`>

Promise resolving to updated webhook

#### Defined in

[managers/webhook-manager.ts:162](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L162)

### enable

▸ **enable**(`webhookId`): `Promise`<`WebhookDTO`>

Enable a webhook (Admin)

#### Parameters

| Name | Type |
|  --- | --- |
| `webhookId` | `string` |


#### Returns

`Promise`<`WebhookDTO`>

#### Defined in

[managers/webhook-manager.ts:178](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L178)

### disable

▸ **disable**(`webhookId`): `Promise`<`WebhookDTO`>

Disable a webhook (Admin)

#### Parameters

| Name | Type |
|  --- | --- |
| `webhookId` | `string` |


#### Returns

`Promise`<`WebhookDTO`>

#### Defined in

[managers/webhook-manager.ts:185](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L185)

### delete

▸ **delete**(`webhookId`): `Promise`<{ `message`: `string` ; `hookId`: `string`  }>

Delete a webhook (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `webhookId` | `string` | UUID of the webhook to delete |


#### Returns

`Promise`<{ `message`: `string` ; `hookId`: `string`  }>

Promise resolving to deletion confirmation

#### Defined in

[managers/webhook-manager.ts:195](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L195)

### get

▸ **get**(`hookId`, `queryParams?`): `Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Trigger a webhook with GET method

Sends a GET request through the webhook proxy. Returns the full response
including execution metadata and raw data from the target.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `hookId` | `string` | Webhook ID to trigger |
| `queryParams?` | `Record`<`string`, `string`> | Optional query parameters |


#### Returns

`Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Promise resolving to trigger response with metadata and data

**`Example`**

```typescript
// Fetch data from external API via webhook proxy
const result = await sdk.webhooks.get('user-directory-webhook');
console.log('Success:', result.success);
console.log('Data:', result.data); // Raw data from target
```

#### Defined in

[managers/webhook-manager.ts:230](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L230)

### trigger

▸ **trigger**(`hookId`, `body`): `Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Trigger a webhook with POST method

Sends data to the configured webhook target. The caller's identity
(user/business/tenant) is included in the request context.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `hookId` | `string` | Webhook ID to trigger |
| `body` | `unknown` | Payload to send |


#### Returns

`Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Promise resolving to trigger response with execution metadata

**`Example`**

```typescript
const result = await sdk.webhooks.trigger('order-webhook', {
  orderId: 'order-123',
  action: 'created',
  items: [...]
});

console.log('Success:', result.success);
console.log('Execution ID:', result.executionId);
console.log('Response:', result.data);
```

#### Defined in

[managers/webhook-manager.ts:257](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L257)

### triggerAndWait

▸ **triggerAndWait**(`hookId`, `body`, `timeoutMs?`): `Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Trigger a webhook and wait for async callback

Use this for workflow systems (n8n, Zapier) that need time to process
and return results via callback. The SDK will wait for the callback
up to the specified timeout.

#### Parameters

| Name | Type | Default value | Description |
|  --- | --- | --- | --- |
| `hookId` | `string` | `undefined` | Webhook ID to trigger |
| `body` | `unknown` | `undefined` | Payload to send |
| `timeoutMs` | `number` | `30000` | Max time to wait for callback (default: 30s) |


#### Returns

`Promise`<`WebhookTriggerResponseDTO`<`unknown`>>

Promise resolving when callback received or timeout

**`Example`**

```typescript
// Trigger AI workflow and wait for result
const result = await sdk.webhooks.triggerAndWait(
  'ai-analysis-webhook',
  { documentId: 'doc-123', analysisType: 'sentiment' },
  60000 // Wait up to 60 seconds
);

if (result.success) {
  console.log('Analysis:', result.data);
}
```

#### Defined in

[managers/webhook-manager.ts:296](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L296)

### getExecutions

▸ **getExecutions**(`options?`): `Promise`<`PaginatedResponseDTO`<`WebhookExecutionDTO`>>

Get webhook execution history (Admin)

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | [`WebhookExecutionQueryOptions`](/sdk-reference/interfaces/webhookexecutionqueryoptions) | Filter and pagination options |


#### Returns

`Promise`<`PaginatedResponseDTO`<`WebhookExecutionDTO`>>

Promise resolving to paginated executions

**`Example`**

```typescript
// Get recent failed executions
const failed = await sdk.webhooks.getExecutions({ status: 'FAILED' });

// Get executions for specific webhook
const executions = await sdk.webhooks.getExecutions({ 
  webhookId: 'webhook-123',
  dateFrom: '2024-01-01'
});
```

#### Defined in

[managers/webhook-manager.ts:326](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L326)

### getExecutionById

▸ **getExecutionById**(`executionId`): `Promise`<`WebhookExecutionDTO`>

Get execution details by ID (Admin)

#### Parameters

| Name | Type |
|  --- | --- |
| `executionId` | `string` |


#### Returns

`Promise`<`WebhookExecutionDTO`>

#### Defined in

[managers/webhook-manager.ts:333](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L333)

### getWebhookService

▸ **getWebhookService**(): [`WebhookService`](/sdk-reference/classes/webhookservice)

Get the full webhook service for advanced operations

#### Returns

[`WebhookService`](/sdk-reference/classes/webhookservice)

WebhookService instance with full API access

#### Defined in

[managers/webhook-manager.ts:342](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/webhook-manager.ts#L342)