# Webhook

特定のイベントが発生したとき、Queuetyは外部URLにHTTP POST通知を送信できます。Webhookを使って、監視システム、Slack、カスタムダッシュボードと連携できます。

## 対応イベント

| イベント | 発生するタイミング |
|---|---|
| `job.completed` | 通常のハンドラージョブまたは`Contracts\Job`クラスが正常に終了したとき（ワークフローステップや状態マシンアクションでは発生しません） |
| `job.failed` | 試行中に例外が発生し、再試行が予定されたとき |
| `job.buried` | ジョブがすべての再試行を使い切ったとき |
| `workflow.failed` | ワークフローステップが恒久的に失敗したとき |

## Webhookの登録

PHP経由:

```php
$id = Queuety::webhook_notifier()->register( 'job.buried', 'https://hooks.slack.com/services/...' );
```

CLI経由で確認します。

```bash
wp queuety webhook add job.buried https://hooks.slack.com/services/...
wp queuety webhook add workflow.failed https://monitoring.example.com/queuety
```

## Webhookの一覧

```php
$webhooks = Queuety::webhook_notifier()->list();
```

```bash
wp queuety webhook list
```

## Webhookの削除

```php
Queuety::webhook_notifier()->remove( $webhook_id );
```

```bash
wp queuety webhook remove 3
```

## ペイロード形式

イベントの発生時、QueuetyはHTTP POSTリクエストを送り、本文にはJSONを含めます。ペイロードの形式は常に次のとおりです。

```json
{
    "event": "job.buried",
    "data": {
        "job_id": 42,
        "handler": "send_email",
        "queue": "emails",
        "error_message": "Connection timed out"
    },
    "timestamp": "2025-03-15T14:30:00Z"
}
```

ワークフローの失敗の場合:

```json
{
    "event": "workflow.failed",
    "data": {
        "workflow_id": 7,
        "job_id": 42,
        "handler": "CallLlmStep",
        "error_message": "API rate limit exceeded"
    },
    "timestamp": "2025-03-15T14:30:00Z"
}
```

Webhookの配信はベストエフォートです。ワーカーは登録された各URLに順番にリクエストを送ります。ストリームのタイムアウトは1秒で、配信の失敗は無視されます。そのため、応答の遅いエンドポイントはURLごとにワーカーを最大約1秒停止させることがありますが、ジョブが失敗することはありません。

## 活用例

- **Slack通知。** ジョブが隔離されたりワークフローが失敗したりしたときに通知を受け取れます。
- **PagerDutyとの連携。** 重大なジョブの失敗時にインシデントを発生させます。
- **カスタムダッシュボード。** イベントを独自の監視インフラに送信します。
- **監査記録。** イベントを外部のログサービスに転送します。