# Webhooks

Queuety pode enviar notificações POST HTTP para URLs externas quando eventos específicos ocorrerem. Use webhooks para integrar sistemas de monitoramento, Slack ou painéis personalizados.

## Eventos compatíveis

| Evento | Disparado quando |
|---|---|
| `job.completed` | Uma tarefa de handler simples ou uma classe `Contracts\Job` termina com sucesso (não é disparado para etapas de fluxo de trabalho nem ações de máquina de estados) |
| `job.failed` | Uma tentativa gera uma exceção e um novo processamento é agendado |
| `job.buried` | Uma tarefa esgota todas as tentativas de processamento |
| `workflow.failed` | Uma etapa do fluxo de trabalho falha permanentemente |

## Registrando webhooks

Por meio de PHP:

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

Por meio de CLI:

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

## Listando webhooks

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

```bash
wp queuety webhook list
```

## Removendo webhooks

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

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

## Formato do payload

Quando um evento é disparado, Queuety envia uma solicitação POST HTTP com um corpo JSON. O payload sempre tem este formato:

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

Em caso de falhas no fluxo de trabalho:

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

A entrega de webhooks é feita no melhor esforço possível. O worker envia uma solicitação a cada URL registrado, em sequência, com um tempo limite de um segundo para a resposta, e ignora falhas de entrega. Assim, um endpoint lento pode ocupar o worker por até cerca de um segundo por URL, mas nunca faz a tarefa falhar.

## Casos de uso

- **Alertas Slack.** Receba notificações quando tarefas forem colocadas em espera ou fluxos de trabalho falharem.
- **Integração PagerDuty.** Acione incidentes para falhas críticas em tarefas.
- **Painéis personalizados.** Transmita eventos para sua própria infraestrutura de monitoramento.
- **Trilha de auditoria.** Encaminhe eventos para um serviço externo de registro.