# Webhookit

Queuety voi lähettää HTTP POST-ilmoituksia ulkoisiin URL-osoitteisiin tiettyjen tapahtumien yhteydessä. Webhookeilla voit integroida seurantajärjestelmiä, Slack-palveluita tai mukautettuja koontinäyttöjä.

## Tuetut tapahtumat

| Tapahtuma | Käynnistyy, kun |
|---|---|
| `job.completed` | Tavallinen käsittelijätyö tai `Contracts\Job`-luokka valmistuu onnistuneesti (ei käynnisty työnkulun vaiheissa tai tilakoneen toiminnoissa) |
| `job.failed` | Yritys heittää virheen ja uudelleenyritys ajoitetaan |
| `job.buried` | Työn kaikki uudelleenyritykset on käytetty |
| `workflow.failed` | Työnkulun vaihe epäonnistuu pysyvästi |

## Webhookien rekisteröinti

PHP-toiminnolla:

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

CLI-toiminnon kautta:

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

## Webhookien luettelointi

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

```bash
wp queuety webhook list
```

## Webhookien poistaminen

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

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

## Hyötykuorman muoto

Tapahtuman käynnistyessä Queuety lähettää HTTP POST-pyynnön, jonka runko on JSON-muodossa. Hyötykuorman muoto on aina seuraava:

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

Työnkulun virhetilanteissa:

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

Webhookien toimitus on parhaan yrityksen mukainen. Työntekijä lähettää POST-pyynnön vuorollaan jokaiseen rekisteröityyn URL-osoitteeseen yhden sekunnin suoratoistoaikakatkaisulla ja sivuuttaa toimitusvirheet. Hidas päätepiste voi siis viivästyttää työntekijää enintään noin sekunnin kutakin URL-kohtaa kohden, mutta ei koskaan aiheuta työn epäonnistumista.

## Käyttötapaukset

- **Slack-hälytykset.** Saat ilmoituksen, kun työt haudataan tai työnkulut epäonnistuvat.
- **PagerDuty-integraatio.** Käynnistä häiriötilanne kriittisten työvirheiden yhteydessä.
- **Mukautetut koontinäytöt.** Välitä tapahtumia omaan valvontainfrastruktuuriisi.
- **Tarkastusketju.** Välitä tapahtumat ulkoiseen lokipalveluun.