웹훅신호 제공자

추가된 항목: @mastra/core@1.39.0

푸시 기반 이벤트 전달을 위한 구체적인 신호 제공자입니다. 구성 가능한 리소스 ID 추출기와 페이로드를 일치시켜 수신 웹후크 페이로드를 구독된 Agent 스레드로 라우팅합니다.

공개 구독 관리 기능과 기본 제공 handleWebhook() 구현으로 SignalProvider를 확장합니다.

사용예

GitHub 웹훅 이벤트를 구독 스레드로 라우팅합니다.

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에 등록하고 스레드를 구독하세요.

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

생성자 매개변수

id?:

string

= 'webhook-signals'

Provider 인스턴스의 고유 식별자입니다.

name?:

string

= 'Webhook Signals'

사람이 읽을 수 있는 이름입니다.

extractResourceId?:

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

= `payload.resource` 또는 `payload.externalResourceId`가 있으면 이를 반환

웹훅 페이로드에서 외부 리소스 ID를 추출합니다. 이벤트를 건너뛰려면 undefined를 반환하세요. 여러 리소스와 일치시키기 위해 배열을 반환할 수 있습니다.

buildNotification?:

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

= `{ source: id, kind: 'webhook-event', summary, payload }`를 반환

웹훅 페이로드와 일치하는 구독으로 알림 객체를 구성합니다.

행동 양식

구독 관리

subscribeThread(target, externalResourceId, metadata?)

특정 외부 리소스에 대한 웹훅 이벤트를 수신하려면 스레드를 구독하세요.

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

보고:SignalSubscription

target:

SignalProviderTarget

구독할 스레드입니다. threadId와 resourceId를 포함해야 합니다.

externalResourceId:

string

모니터링할 외부 리소스입니다(예: 저장소의 전체 이름).

metadata?:

Record<string, unknown>

구독과 함께 저장할 추가 데이터입니다.

unsubscribeThread(target, externalResourceId)

특정 외부 리소스에서 스레드 구독을 취소합니다.

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

보고:boolean

웹훅 처리

handleWebhook(request)

들어오는 웹훅 요청을 처리합니다. 페이로드에서 리소스 ID를 추출하고, 일치하는 구독을 찾고, 각각에 대한 알림을 작성하고, 호출합니다.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 } }>

N이 알림을 수신한 구독 수인 { status: 200, body: { matched: N } }을 반환합니다. 리소스 ID를 추출할 수 없거나 일치하는 구독이 없으면 matched: 0을 반환합니다.

request:

object

수신 웹훅 요청입니다.

object

body:

unknown

구문 분석된 웹훅 페이로드입니다.

headers:

Record<string, string>

웹훅 요청의 HTTP 헤더입니다.

정적 신호 공장

WebhookSignalProvider.signals.subscribe(externalResourceId)

현재 스레드를 외부 리소스에 구독하는 반응 신호 입력을 만듭니다.

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

보고:{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }

WebhookSignalProvider.signals.unsubscribe(externalResourceId)

외부 리소스에서 현재 스레드를 구독 취소하는 반응적 신호 입력을 만듭니다.

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

보고:{ type: 'reactive'; tagName: string; contents: string; attributes: { resource: string } }