# Webhooks

Queuety kann bei bestimmten Ereignissen HTTP-POST-Benachrichtigungen an externe URLs senden. Mit Webhooks kannst du Überwachungssysteme, Slack oder eigene Dashboards integrieren.

## Unterstützte Ereignisse

| Ereignis | Auslöser |
|---|---|
| `job.completed` | Ein einfacher Handler-Job oder eine Klasse `Contracts\Job` wird erfolgreich abgeschlossen (wird nicht bei Workflow-Schritten oder Aktionen einer State Machine ausgelöst) |
| `job.failed` | Ein Versuch löst eine Ausnahme aus und ein erneuter Versuch wird geplant |
| `job.buried` | Für einen Job sind alle Wiederholungsversuche ausgeschöpft |
| `workflow.failed` | Ein Workflow-Schritt schlägt endgültig fehl |

## Webhooks registrieren

Über PHP:

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

Über 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 auflisten

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

```bash
wp queuety webhook list
```

## Webhooks entfernen

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

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

## Payload-Format

Wenn ein Ereignis eintritt, sendet Queuety eine HTTP-POST-Anfrage mit einem JSON-Body. Die Payload hat immer diese Form:

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

Bei Workflow-Fehlern:

```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"
}
```

Die Zustellung von Webhooks erfolgt nach bestem Bemühen. Der Worker sendet nacheinander einen POST an jedes registrierte URL, wobei das Stream-Timeout eine Sekunde beträgt. Zustellfehler werden ignoriert. Ein langsamer Endpunkt kostet den Worker daher bis zu etwa eine Sekunde pro URL, führt aber niemals zum Fehlschlagen des Jobs.

## Anwendungsfälle

- **Slack-Benachrichtigungen.** Lass dich benachrichtigen, wenn Jobs im Hintergrund abgelegt werden oder Workflows fehlschlagen.
- **PagerDuty-Integration.** Löse bei kritischen Job-Fehlern Vorfälle aus.
- **Eigene Dashboards.** Übertrage Ereignisse an deine eigene Überwachungsinfrastruktur.
- **Prüfpfad.** Leite Ereignisse an einen externen Protokollierungsdienst weiter.