# Webhooks

Queuety puede enviar notificaciones HTTP POST a URL externas cuando se producen eventos específicos. Use webhooks para integrar con sistemas de supervisión, Slack o paneles personalizados.

## Eventos compatibles

| Evento | Se activa cuando |
|---|---|
| `job.completed` | Un trabajo de handler normal o una clase `Contracts\Job` finaliza correctamente (no se activa en pasos de flujos de trabajo ni acciones de máquinas de estado) |
| `job.failed` | Un intento genera una excepción y se programa un reintento |
| `job.buried` | Un trabajo agota todos los intentos de reintento |
| `workflow.failed` | Falla permanentemente un paso del flujo de trabajo |

## Registrar webhooks

Mediante PHP:

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

Mediante CLI:

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

## Listar webhooks

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

```bash
wp queuety webhook list
```

## Eliminar webhooks

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

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

## Formato del payload

Cuando se activa un evento, Queuety envía una solicitud HTTP POST con un cuerpo JSON. El payload siempre tiene esta estructura:

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

Para fallos de flujos de trabajo:

```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 entrega de webhooks se realiza según el mejor esfuerzo posible. El worker envía una solicitud a cada URL registrado, de una en una, con un tiempo de espera de un segundo para el flujo de datos, e ignora los fallos de entrega. Por tanto, un endpoint lento puede costarle al worker hasta un segundo por URL, pero nunca provoca el fallo del trabajo.

## Casos de uso

- **Alertas Slack.** Reciba notificaciones cuando los trabajos queden enterrados o fallen los flujos de trabajo.
- **Integración con PagerDuty.** Active incidentes ante fallos críticos de trabajos.
- **Paneles personalizados.** Envíe eventos a su propia infraestructura de monitorización.
- **Registro de auditoría.** Reenvíe eventos a un servicio de registro externo.