WebhookSignalProvider

Ajouté dans : @mastra/core@1.39.0

Provider de Signal concret pour la distribution d'événements par envoi push. Achemine les charges utiles des webhooks entrants vers les threads d'Agent abonnés en recherchant une correspondance au moyen d'un extracteur configurable d'identifiant de ressource.

Étend SignalProvider avec une gestion publique des abonnements et une implémentation intégrée de handleWebhook().

Exemple d'utilisation

Acheminez les événements des webhooks GitHub vers les threads abonnés :

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,
  }),
})

Enregistrez le Provider auprès d'un Agent et abonnez un 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

Paramètres du constructeur

id?:

string

= 'webhook-signals'

Identifiant unique de l'instance du Provider.

name?:

string

= 'Webhook Signals'

Nom lisible par les utilisateurs.

extractResourceId?:

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

= Renvoie `payload.resource` ou `payload.externalResourceId` si présent

Extrait l'identifiant de la ressource externe dans la charge utile d'un webhook. Renvoie undefined pour ignorer l'événement. Peut renvoyer un tableau afin d'établir une correspondance avec plusieurs ressources.

buildNotification?:

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

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

Construit l'objet de notification à partir de la charge utile d'un webhook et de l'abonnement correspondant.

Méthodes

Gestion des abonnements

subscribeThread(target, externalResourceId, metadata?)

Abonne un thread aux événements des webhooks d'une ressource externe précise.

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

Renvoie : SignalSubscription

target:

SignalProviderTarget

Thread à abonner. Doit inclure threadId et resourceId.

externalResourceId:

string

Ressource externe à surveiller (par exemple, le nom complet d’un dépôt).

metadata?:

Record<string, unknown>

Données supplémentaires à stocker avec l'abonnement.

unsubscribeThread(target, externalResourceId)

Désabonne un thread d'une ressource externe précise.

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

Renvoie : boolean

Gestion des webhooks

handleWebhook(request)

Traite une requête de webhook entrante. Extrait l'identifiant de ressource de la charge utile, recherche les abonnements correspondants, construit une notification pour chacun, puis appelle notify().

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

Renvoie : Promise<{ status: number; body: { matched: number } }>

Renvoie { status: 200, body: { matched: N } }, où N correspond au nombre d'abonnements qui ont reçu des notifications. Renvoie matched: 0 lorsqu'aucun identifiant de ressource n'a pu être extrait ou qu'aucun abonnement ne correspond.

request:

object

Requête de webhook entrante.

object

body:

unknown

Charge utile analysée du webhook.

headers:

Record<string, string>

En-têtes HTTP de la requête de webhook.

Fabriques de Signals statiques

WebhookSignalProvider.signals.subscribe(externalResourceId)

Crée une entrée de Signal réactive qui abonne le thread actuel à une ressource externe.

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

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

WebhookSignalProvider.signals.unsubscribe(externalResourceId)

Crée une entrée de Signal réactive qui désabonne le thread actuel d'une ressource externe.

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

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