WebhookSignalProvider

新增於： @mastra/core@1.39.0

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

擴充 SignalProvider，提供公開的 subscription 管理功能與內建的 handleWebhook() 實作。

使用範例

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

src/signals/webhook.ts

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 訂閱：

src/mastra/index.ts

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

= 'webhook-signals'

Provider instance 的不重複識別碼。

name?:

string

= 'Webhook Signals'

方便閱讀的名稱。

extractResourceId?:

(payload: unknown) => string | string[] | undefined

= 若存在，傳回 `payload.resource` 或 `payload.externalResourceId`

從 webhook payload 擷取外部 resource ID。傳回 undefined 可略過 event，也可傳回陣列以比對多項資源。

buildNotification?:

(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput

= 傳回 `{ source: id, kind: 'webhook-event', summary, payload }`

使用 webhook payload 與符合的 subscription 建立通知物件。

方法

Subscription 管理

subscribeThread(target, externalResourceId, metadata?)

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

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 對特定外部資源的訂閱。

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()。

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。

object

body:

unknown

已解析的 webhook payload。

headers:

Record<string, string>

webhook request 中的 HTTP header。

靜態 Signal factory

WebhookSignalProvider.signals.subscribe(externalResourceId)

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

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

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

WebhookSignalProvider.signals.unsubscribe(externalResourceId)

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

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

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