# Webhooks

Queuety can send HTTP POST notifications to external URLs when specific events occur. Use webhooks to integrate with monitoring systems, Slack, or custom dashboards.

## Supported events

| Event | Fired when |
|---|---|
| `job.completed` | A job finishes successfully |
| `job.failed` | A job throws an exception |
| `job.buried` | A job exhausts all retry attempts |
| `workflow.failed` | A workflow step fails permanently |

## Registering webhooks

Via PHP:

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

Via CLI:

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

## Listing webhooks

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

```bash
wp queuety webhook list
```

## Removing webhooks

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

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

## Payload format

When an event fires, Queuety sends an HTTP POST request with a JSON body. The payload always has the shape:

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

For workflow failures:

```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 delivery is fire-and-forget. Queuety uses a very short timeout and ignores delivery failures so workers are not blocked by slow or unavailable webhook endpoints.

## Use cases

- **Slack alerts.** Get notified when jobs are buried or workflows fail.
- **PagerDuty integration.** Trigger incidents for critical job failures.
- **Custom dashboards.** Stream events to your own monitoring infrastructure.
- **Audit trail.** Forward events to an external logging service.