Skip to main content
A Niadra avisa os seus sistemas quando algo acontece na memória, por webhooks assinados. Há dois tipos. Uma assinatura de webhook entrega cada ocorrência de um tipo de evento, como action.recorded. Um gatilho é uma regra sua sobre o que a memória sabe, com parâmetros, janela e deduplicação por sujeito, como “promessa da empresa vencida há um dia”. Nos dois casos, a Niadra avisa por webhook, e quem age é o seu agente ou o seu sistema. Gatilho nunca chama sistema de registro, nunca abre ticket, nunca manda mensagem ao cliente final e nunca ramifica.

Tipos de evento de saída

Endpoints, assinaturas e regras de gatilho são configuração versionada na API de controle, alterada por diffs que uma pessoa aprova. Todo endpoint pertence a uma fonte com classe de audiência, e uma regra só é aceita, e só dispara, se a condição e o conteúdo do aviso puderem ser lidos por essa fonte. trait.present(overdue_invoices) nunca chega a um sistema de marketing.

O catálogo de gatilhos

Condições novas entram pelo catálogo do produto, nunca por texto livre. Uma regra dispara no máximo uma vez por sujeito por janela (24 horas por padrão), com teto de 100 disparos por minuto por espaço e de 50 regras por espaço. Condições por evento são avaliadas logo depois que a memória é atualizada; condições por tempo, a cada 5 minutos. Um disparo atrasado sai marcado como late ou é suprimido, conforme a regra.
Antes de ligar uma regra, rode um teste a seco por POST /v1/triggers/dry-run: a regra em teste traz rule_id, condition, params, o endpoint_id de destino, window_hours (24 por padrão, até 90 dias) e late_policy (deliver_marked ou suppress). A resposta, sobre os últimos 30 dias, diz quantos disparos teriam acontecido (would_fire), com uma amostra, e traz target_problem quando a fonte do endpoint não pode ler o conteúdo do aviso. Ajuste os parâmetros antes de acionar qualquer pessoa. Pede o papel integration ou uma chave admin.
Exemplo: “avisar o CRM um dia depois de uma visita técnica perdida”. Quando a visita remarcada da Marina passa um dia do prazo sem ação que a feche, a Niadra manda trigger.fired para o endpoint do CRM, e o agente do seu CRM remarca a visita.

Como é uma entrega

As entregas seguem o formato aberto Standard Webhooks.
O corpo leva ids, a regra e a versão, estado e ponteiros para as evidências. Nunca leva conteúdo de conversa. O sujeito pode trazer o system_id do cliente no seu próprio sistema, nunca telefone, e-mail ou número de documento. links.open é a rota da API que abre o item, e ela só funciona com uma credencial do seu espaço que tenha o escopo para isso. Toda entrega traz três cabeçalhos:
  • 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

O segredo é gravado uma vez, pelo Console ou por PUT /v1/secrets/webhook/{id}, e começa com whsec_; a chave é a parte em base64 depois do prefixo. Confira sobre o corpo cru, antes de interpretar o JSON.

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 por até 24 horas. Depois disso, a entrega vai para a fila de mortos, visível no Console e guardada por 7 dias.
  • Endpoint que falha sem parar por 24 horas é desativado, e o seu espaço recebe o aviso.
  • Saída controlada. Toda chamada para fora passa por um proxy de saída com lista de permissão por espaço. Endereços privados, de metadados da nuvem e de loopback são bloqueados, o DNS é resolvido e fixado a cada tentativa, e só sai HTTPS.
Responda com qualquer 2xx rápido e faça o trabalho de forma assíncrona. Uma entrega fica pending, delivered, failing enquanto tenta de novo, ou dead. Essas rotas pedem uma pessoa do Console com o papel integration (os disparos aceitam também analysis) ou uma chave de escopo admin. Para inspecionar entregas, use Entregas de webhook; para mandar de novo uma entrega morta, com o mesmo webhook-id, use Reenviar uma entrega. Os disparos, com a regra, a versão e as evidências, estão em Disparos de gatilho.

Próximos passos

Padrões

os sinais que trait.present pode observar.

Webhooks dos seus sistemas

o outro sentido, eventos chegando.

Aproveitamento do contexto

a taxa de repetição por trás de context_use.repetition_rate.

Comprovantes e auditoria

comprovantes entregues ao seu SIEM pelo mesmo mecanismo.