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

# WebhookSignalProvider

**追加バージョン:** `@mastra/core@1.39.0`

Push 型イベント配信のための具象 Signal Provider です。設定可能な Resource ID 抽出関数を使用して Payload を照合し、受信した Webhook Payload を購読中の Agent Thread にルーティングします。

[`SignalProvider`](https://mastra.zisheng.pro/ja/reference/signals/signal-provider) を拡張し、公開 Subscription 管理機能と組み込みの `handleWebhook()` 実装を提供します。

## 使用例

GitHub Webhook イベントを購読中の 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
```

## コンストラクターのパラメーター

**id** (`string`): Provider インスタンスの一意の識別子。 (Default: `'webhook-signals'`)

**name** (`string`): 人が読める名前。 (Default: `'Webhook Signals'`)

**extractResourceId** (`(payload: unknown) => string | string[] | undefined`): Webhook Payload から外部 Resource ID を抽出します。イベントをスキップするには undefined を返します。複数の Resource と照合するために配列を返すこともできます。 (Default: ``Returns `payload.resource` or `payload.externalResourceId` if present``)

**buildNotification** (`(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput`): Webhook Payload と一致した Subscription から通知オブジェクトを構築します。 (Default: `` Returns `{ source: id, kind: 'webhook-event', summary, payload }` ``)

## メソッド

### Subscription の管理

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

特定の外部 Resource の Webhook イベントを受信するよう Thread を購読します。

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

戻り値: `SignalSubscription`

**target** (`SignalProviderTarget`): 購読する Thread。threadId と resourceId を含める必要があります。

**externalResourceId** (`string`): 監視する外部 Resource（たとえば、リポジトリの完全な名前）。

**metadata** (`Record<string, unknown>`): Subscription とともに保存する追加データ。

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

特定の外部 Resource に対する Thread の購読を解除します。

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

戻り値: `boolean`

### Webhook の処理

#### `handleWebhook(request)`

受信した Webhook リクエストを処理します。Payload から Resource ID を抽出し、一致する 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 } }>`

通知を受信した Subscription 数を `N` として、`{ status: 200, body: { matched: N } }` を返します。Resource ID を抽出できない場合や、一致する Subscription がない場合は `matched: 0` を返します。

**request** (`object`): 受信した Webhook リクエスト。

**request.body** (`unknown`): 解析済みの Webhook Payload。

**request.headers** (`Record<string, string>`): Webhook リクエストの HTTP Header。

### 静的 Signal Factory

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

現在の Thread が外部 Resource を購読する Reactive Signal Input を作成します。

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

戻り値: `{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`

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

現在の Thread が外部 Resource の購読を解除する Reactive Signal Input を作成します。

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

戻り値: `{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }`