# Webhook

Queuety può inviare notifiche POST HTTP a URL esterni al verificarsi di eventi specifici. Usate i webhook per integrare sistemi di monitoraggio, Slack o dashboard personalizzate.

## Eventi supportati

| Evento | Quando viene attivato |
|---|---|
| `job.completed` | Un job con gestore semplice o una classe `Contracts\Job` viene completato correttamente (non si attiva per i passaggi dei workflow né per le azioni delle macchine a stati) |
| `job.failed` | Un tentativo genera un'eccezione e viene pianificato un nuovo tentativo |
| `job.buried` | Un job esaurisce tutti i tentativi disponibili |
| `workflow.failed` | Un passaggio del workflow fallisce definitivamente |

## Registrare i webhook

Tramite PHP:

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

Tramite CLI:

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

## Elencare i webhook

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

```bash
wp queuety webhook list
```

## Rimuovere i webhook

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

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

## Formato del payload

Quando si verifica un evento, Queuety invia una richiesta POST HTTP con un corpo JSON. Il payload ha sempre questa struttura:

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

Per gli errori dei workflow:

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

La consegna dei webhook avviene in modalità best effort. Il worker invia una richiesta a ogni URL registrato, a turno, con un timeout dello stream di un secondo e ignora gli errori di consegna; un endpoint lento costa al worker fino a circa un secondo per URL, ma non causa mai il fallimento del job.

## Casi d'uso

- **Avvisi Slack.** Ricevete una notifica quando i job vengono messi in coda di quarantena o i workflow non riescono.
- **Integrazione PagerDuty.** Attivate incidenti per gli errori critici dei job.
- **Dashboard personalizzate.** Trasmettete gli eventi alla vostra infrastruttura di monitoraggio.
- **Traccia di controllo.** Inoltrate gli eventi a un servizio di registrazione esterno.