> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.omni-ward.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Eventos assinados com HMAC-SHA256.

Cadastre uma URL HTTPS pública em **Webhooks**, no console. Endereços internos são bloqueados no cadastro e a cada entrega.

## Eventos

| Evento | Quando |
| - | - |
| `verification.started` | A pessoa abriu a sessão |
| `verification.step_changed` | Uma etapa foi concluída |
| `verification.completed` | A sessão terminou |
| `verification.failed` | A sessão falhou |
| `verification.cancelled` | A sessão foi cancelada |
| `verification.expired` | A sessão expirou |
| `case.decided` | Um caso de revisão manual foi decidido |

## Formato

```http theme={null}
POST /sua-rota
omni-ward-signature: t=1762300000,v1=5f8a…

{
  "id": "uuid-da-entrega",
  "type": "verification.completed",
  "environment": "SANDBOX",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": { "sessionId": "…", "outcome": "approved" }
}
```

Os payloads trazem identificadores e situação, nunca dados pessoais. Busque os detalhes com [`GET /v1/sessions/{id}`](https://api-docs.omni-ward.com/api-reference/consultar-sessao).

## Verifique a assinatura

```typescript Node.js theme={null}
import { verifyWebhookSignature } from '@omni-ward/sdk-node';

// rawBody: o corpo exatamente como chegou, antes de qualquer parsing.
const ok = verifyWebhookSignature({
  secret: process.env.OMNI_WARD_WEBHOOK_SECRET!,
  rawBody,
  signature: req.headers['omni-ward-signature'],
});
if (!ok) return res.status(400).end();
```

```python Python theme={null}
import hmac, hashlib, time

def verify(secret: str, raw_body: bytes, header: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)
```

## Entrega

* Responda 2xx em até 10 segundos.
* Falhas são repetidas até 8 vezes, com intervalos crescentes.
* A entrega é "ao menos uma vez": use o campo `id` para descartar duplicatas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.