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

# 웹훅신호 제공자

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

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

공개 구독 관리 기능과 기본 제공 `handleWebhook()` 구현으로 [`SignalProvider`](https://mastra.zisheng.pro/ko/reference/signals/signal-provider)를 확장합니다.

## 사용예

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

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

```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`): 웹훅 페이로드에서 외부 리소스 ID를 추출합니다. 이벤트를 건너뛰려면 undefined를 반환하세요. 여러 리소스와 일치시키기 위해 배열을 반환할 수 있습니다. (Default: `` `payload.resource` 또는 `payload.externalResourceId`가 있으면 이를 반환 ``)

**buildNotification** (`(payload: unknown, subscription: SignalSubscription) => SendNotificationSignalInput`): 웹훅 페이로드와 일치하는 구독으로 알림 객체를 구성합니다. (Default: `` `{ source: id, kind: 'webhook-event', summary, payload }`를 반환 ``)

## 행동 양식

### 구독 관리

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

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

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

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

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

보고:`boolean`

### 웹훅 처리

#### `handleWebhook(request)`

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

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

**request** (`object`): 수신 웹훅 요청입니다.

**request.body** (`unknown`): 구문 분석된 웹훅 페이로드입니다.

**request.headers** (`Record<string, string>`): 웹훅 요청의 HTTP 헤더입니다.

### 정적 신호 공장

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

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

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

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

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

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

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

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