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

# 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`](https://mastra.zisheng.pro/fr/reference/signals/signal-provider) 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 :

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

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

## Paramètres du constructeur

**id** (`string`): Identifiant unique de l'instance du Provider. (Default: `'webhook-signals'`)

**name** (`string`): Nom lisible par les utilisateurs. (Default: `'Webhook Signals'`)

**extractResourceId** (`(payload: unknown) => string | string[] | undefined`): 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. (Default: ``Renvoie `payload.resource` ou `payload.externalResourceId` si présent``)

**buildNotification** (`(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput`): Construit l'objet de notification à partir de la charge utile d'un webhook et de l'abonnement correspondant. (Default: `` Renvoie `{ source: id, kind: 'webhook-event', summary, payload }` ``)

## Méthodes

### Gestion des abonnements

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

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

```typescript
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.

```typescript
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()`.

```typescript
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.

**request.body** (`unknown`): Charge utile analysée du webhook.

**request.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.

```typescript
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.

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

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