Webhooks - Omni-Ward

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

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}.

Verifique a assinatura

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();

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.