Gatilhos e webhooks

Tipos de evento de saída

• uma regra cujo endpoint não pode receber o aviso: é um fluxo de SIEM, não assina trigger.fired, é de uma fonte de análise ou de exportação, recebe um aviso de identidade sendo agente de atendimento, ou não tem finalidade nem audiência em comum com o padrão do aviso;
• uma regra trait.present que nomeia um padrão desligado ou que não existe;
• uma regra context_use.repetition_rate com parâmetros que a varredura não consegue ler ou com uma source_id que não existe no espaço;
• um endpoint que assina um tipo de evento que a Niadra não manda: a lista aceita é exatamente a tabela acima;
• um endpoint ou um mapeamento novo para uma fonte cortada;
• um documento com mais de 50 regras de aviso.

O desfecho de cada atendimento

{
  "id": "0192f8d1-2a40-7b3c-8d4e-5f6a7b8c9d0e",
  "type": "conversation.outcome",
  "created_at": "2026-09-23T14:21:07+00:00",
  "tenant": "0192f0a0-1b2c-7d3e-8f40-5a6b7c8d9e01",
  "subject": { "pseudonym": "p_kvkv3okp7vnw3mqs", "kind": "person" },
  "data": {
    "episode_id": "0192f8c9-7d10-7e2f-9a3b-4c5d6e7f8091",
    "version": 1,
    "session_id": "0192f8b4-1c20-7a3b-8c4d-5e6f7a8b9c0d",
    "conversation_id": "wa-8812",
    "source_id": "0192f5a0-0000-7000-8000-00000000c001",
    "channel": "whatsapp",
    "intent": "complaint",
    "category": "billing",
    "outcome": "pending",
    "by": "extraction",
    "started_at": "2026-09-23T14:00:12+00:00",
    "ended_at": "2026-09-23T14:19:40+00:00",
    "as_of": "2026-09-23T14:19:40+00:00",
    "open_item_ids": ["0192f8c9-7d11-7f40-8b5c-6d7e8f90a1b2"]
  },
  "links": { "open": "/v1/history/items/0192f8c9-7d10-7e2f-9a3b-4c5d6e7f8091" }
}

O catálogo de gatilhos

Condições sobre uma fonte

• source.silent observa as fontes que mandaram eventos nos últimos 30 dias. Cada silêncio é uma ocorrência própria: a fonte que volta e cala de novo avisa de novo.
• context_use.repetition_rate lê a medição diária de Aproveitamento do contexto. Dispara quando, nos últimos window_days dias (7 por padrão, até 90), as perguntas repetidas passam da fração above (0,2 por padrão) das perguntas da fonte, com pelo menos min_questions perguntas (30 por padrão) para o número valer. Sem source_id, cada fonte é observada por si. O grupo de controle de um experimento fica de fora, porque nunca recebeu o contexto. Um período acima do limite avisa uma vez, contado do dia em que começou; se a taxa cair e voltar a subir, sai um aviso novo. O aviso traz em data.detail as perguntas (questions), as repetidas (repeated), a taxa (rate), o limite (above), a janela (window_days) e o dia em que o período começou (above_since), e links.open aponta para /v1/context-use?source_id=.... Parâmetros que a varredura não consegue ler, ou uma source_id que não existe no espaço, são recusados quando o diff é enviado e quando é aprovado.

Como é uma entrega

{
  "id": "0192f8d0-7e31-7a4b-9c5d-3e4f5a6b7c8d",
  "type": "trigger.fired",
  "created_at": "2026-09-23T15:05:00+00:00",
  "tenant": "0192f0a0-1b2c-7d3e-8f40-5a6b7c8d9e01",
  "subject": { "pseudonym": "p_kvkv3okp7vnw3mqs", "kind": "person" },
  "data": {
    "firing_id": "0192f7e0-3a41-7b52-8c63-4d5e6f708192",
    "rule_id": "overdue-visit",
    "rule_version": "4",
    "condition": "promise.overdue",
    "window_key": "24h:20719",
    "late": false,
    "membership_version": 7,
    "as_of": "2026-09-23T15:04:58+00:00",
    "evidence": [{ "kind": "open_item", "id": "0192f7a2-8c41-7e3a-9b5d-2c4e6f8a0b13" }]
  },
  "links": { "open": "/v1/profiles/0192f7a0-3b2e-7d41-8c5a-2e9f4b7a1c03" }
}

• webhook-id: único por mensagem e igual em todas as tentativas. Use para deduplicar.
• webhook-timestamp: segundos Unix. Recuse o que estiver a mais de 5 minutos do seu relógio.
• webhook-signature: v1, seguido do HMAC-SHA256 em base64 de {webhook-id}.{webhook-timestamp}.{corpo}. Durante a rotação do segredo, duas assinaturas separadas por espaço valem ao mesmo tempo.

Confira a assinatura

import base64
import hashlib
import hmac
import time


def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for candidate in headers["webhook-signature"].split(" "):
        version, _, signature = candidate.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret: string, headers: Record<string, string>, body: string): boolean {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((candidate) => {
    const [version, signature] = candidate.split(",");
    if (version !== "v1" || !signature || signature.length !== expected.length) return false;
    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

Garantias de entrega

• Pelo menos uma vez. Uma mensagem pode chegar mais de uma vez; deduplique pelo webhook-id.
• Sem garantia de ordem. As mensagens podem chegar fora de ordem; cada evento traz as_of e versão para você ordenar.
• Novas tentativas com recuo exponencial, de 30 segundos até 4 horas entre elas, por até 24 horas. Depois disso, a entrega vai para a fila de mortos, visível no Console, e é apagada 7 dias depois de criada.
• Endpoint que falha sem parar há 24 horas, sem nenhum sucesso, deixa de receber: as entregas novas para ele vão direto para a fila de mortos com o erro endpoint_failing_24h. Um reenvio manual que dê certo o reabre.
• Saída controlada. Toda chamada para fora sai só por HTTPS e não segue redirecionamento. O endereço é resolvido e conferido a cada tentativa, e a conexão vai ao endereço conferido. Endereços privados, de loopback, link-local (inclusive o de metadados da nuvem), CGNAT, reservados e multicast são recusados.

O feed de avisos

page = niadra.api.notifications(cursor=cursor, limit=100)
for event in page.items:
    handle(event.type, event.data)
cursor = page.next_cursor  # keep it between polls

const page = await niadra.api.notifications({ cursor, limit: 100 });
for (const event of page.items) handle(event.type, event.data);
cursor = page.next_cursor; // keep it between polls

Responder a uma entrega

Próximos passos