> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# WebhookSignalProvider

**新增於：** `@mastra/core@1.39.0`

用於 push 型 event 傳遞的具體 Signal Provider。它會使用可設定的 resource ID extractor 比對 payload，將傳入的 webhook payload 路由至已訂閱的 Agent thread。

擴充 [`SignalProvider`](https://mastra.zisheng.pro/zh-TW/reference/signals/signal-provider)，提供公開的 subscription 管理功能與內建的 `handleWebhook()` 實作。

## 使用範例

將 GitHub webhook event 路由至已訂閱的 thread：

```typescript
import { WebhookSignalProvider } from '@mastra/core/signals'

const webhookProvider = new WebhookSignalProvider({
  extractResourceId: payload => `${payload.repository?.full_name}`,
  buildNotification: (payload, subscription) => ({
    source: 'github-webhook',
    kind: payload.action ?? 'event',
    summary: `${payload.action} on ${subscription.externalResourceId}`,
    payload,
  }),
})
```

向 Agent 註冊，並讓 thread 訂閱：

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'agent',
  signals: [webhookProvider],
})

// subscribe a thread to a specific repo
webhookProvider.subscribeThread({ threadId: 'thread-1', resourceId: 'user-1' }, 'mastra-ai/mastra')

// handle an incoming webhook
const result = await webhookProvider.handleWebhook({
  body: { repository: { full_name: 'mastra-ai/mastra' }, action: 'push' },
  headers: {},
})
// result.matched === 1
```

## Constructor 參數

**id** (`string`): Provider instance 的不重複識別碼。 (Default: `'webhook-signals'`)

**name** (`string`): 方便閱讀的名稱。 (Default: `'Webhook Signals'`)

**extractResourceId** (`(payload: unknown) => string | string[] | undefined`): 從 webhook payload 擷取外部 resource ID。傳回 undefined 可略過 event，也可傳回陣列以比對多項資源。 (Default: `` 若存在，傳回 `payload.resource` 或 `payload.externalResourceId` ``)

**buildNotification** (`(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput`): 使用 webhook payload 與符合的 subscription 建立通知物件。 (Default: `` 傳回 `{ source: id, kind: 'webhook-event', summary, payload }` ``)

## 方法

### Subscription 管理

#### `subscribeThread(target, externalResourceId, metadata?)`

訂閱 thread，使其接收特定外部資源的 webhook event。

```typescript
webhookProvider.subscribeThread(
  { threadId: 'thread-1', resourceId: 'user-1' },
  'mastra-ai/mastra',
  { watchType: 'push' },
)
```

傳回：`SignalSubscription`

**target** (`SignalProviderTarget`): 要訂閱的 thread。必須包含 threadId 與 resourceId。

**externalResourceId** (`string`): 要監控的外部資源，例如 repository 完整名稱。

**metadata** (`Record<string, unknown>`): 與 subscription 一起儲存的其他資料。

#### `unsubscribeThread(target, externalResourceId)`

取消 thread 對特定外部資源的訂閱。

```typescript
const removed = webhookProvider.unsubscribeThread(
  { threadId: 'thread-1', resourceId: 'user-1' },
  'mastra-ai/mastra',
)
```

傳回：`boolean`

### Webhook 處理

#### `handleWebhook(request)`

處理傳入的 webhook request。從 payload 擷取 resource ID、尋找符合的 subscription、為每個 subscription 建立通知，並呼叫 `notify()`。

```typescript
const result = await webhookProvider.handleWebhook({
  body: { repository: { full_name: 'mastra-ai/mastra' }, action: 'push' },
  headers: { 'x-github-event': 'push' },
})
```

傳回：`Promise<{ status: number; body: { matched: number } }>`

傳回 `{ status: 200, body: { matched: N } }`，其中 `N` 是收到通知的 subscription 數量。無法擷取 resource ID 或沒有符合的 subscription 時，傳回 `matched: 0`。

**request** (`object`): 傳入的 webhook request。

**request.body** (`unknown`): 已解析的 webhook payload。

**request.headers** (`Record<string, string>`): webhook request 中的 HTTP header。

### 靜態 Signal factory

#### `WebhookSignalProvider.signals.subscribe(externalResourceId)`

建立 reactive signal 輸入，讓目前 thread 訂閱外部資源。

```typescript
const signal = WebhookSignalProvider.signals.subscribe('mastra-ai/mastra')
```

傳回：`{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`

#### `WebhookSignalProvider.signals.unsubscribe(externalResourceId)`

建立 reactive signal 輸入，讓目前 thread 取消訂閱外部資源。

```typescript
const signal = WebhookSignalProvider.signals.unsubscribe('mastra-ai/mastra')
```

傳回：`{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`