# 网络钩子

特定事件发生时，Queuety 可以向外部 URL 发送 HTTP POST 通知。你可以使用 Webhooks 将其与监控系统、Slack 或自定义仪表板集成。

## 支持的事件

| 事件 | 触发时机 |
|---|---|
| `job.completed` | 普通处理程序任务或 `Contracts\Job` 类成功完成时（工作流步骤或状态机操作不会触发） |
| `job.failed` | 某次尝试抛出异常并安排重试时 |
| `job.buried` | 任务耗尽所有重试次数时 |
| `workflow.failed` | 工作流步骤永久失败时 |

## 注册 Webhooks

通过 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
```

## 列出 Webhooks

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

```bash
wp queuety webhook list
```

## 移除 Webhooks

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

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

## 负载格式

事件触发时，Queuety 会发送带有 JSON 正文的 HTTP POST 请求。负载始终采用以下结构：

```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 发送请求，流式超时为一秒，并忽略投递失败。因此，响应缓慢的端点每次 URL 最多会让工作进程多等待约一秒，但不会导致任务失败。

## 使用场景

- **Slack 告警。** 当作业被搁置或工作流失败时收到通知。
- **PagerDuty 集成。** 为严重作业失败触发事件。
- **自定义仪表板。** 将事件流式传输到你自己的监控基础设施。
- **审计跟踪。** 将事件转发到外部日志服务。