Assinar eventos

Um webhook da TAI é um endereço do seu sistema que recebe, por POST, cada evento assinado. É a forma mais direta de integrar: escolha os eventos uma vez e todos chegam, sem montar automação.

Criar o webhook

1. Em Processos › Central de Automações, aba Webhooks, seção Para onde a TAI envia, clique em Novo webhook.

2. Dê um Nome (“ERP”, “Sistema de folha”) e o Endereço do outro sistema — precisa ser https:// e público (veja requisitos).

3. Em O que enviar, marque os eventos. Tudo de <módulo> assina todos os eventos daquele módulo, inclusive os que surgirem depois. A lista completa está no catálogo de eventos.

4. Marque Enviar também o registro completo se o seu sistema precisa da ficha inteira — por exemplo, o colaborador com documentos e endereço. O registro é lido com a permissão de quem responde pelo webhook: o que essa pessoa não vê, não vai.

5. Se o seu sistema exige um token, abra Avançado e informe o cabeçalho (Authorization, Bearer …). O valor fica guardado cifrado e não aparece de novo.

6. Clique em Criar webhook e copie o segredo: ele aparece uma única vez e é com ele que o seu sistema confere a assinatura.

7. O webhook nasce desligado. Clique em Testar — a TAI envia um exemplo marcado com X-Tai-Teste: true — e, se chegou, ligue o interruptor.

O que chega

Cada evento é um POST com Content-Type: application/json; charset=utf-8:

{
  "id": "evt_48213",
  "tipo": "COLABORADOR_CRIADO",
  "descricao": "Um colaborador é cadastrado",
  "versao": 1,
  "ocorridoEm": "2026-10-06T12:04:51.233Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "colaboradorId": 1813,
    "colaboradorNome": "Ana Ribeiro",
    "gestorId": 1544
  }
}

Campo	Conteúdo
id	Id do evento. O mesmo fato tem sempre o mesmo id
tipo	A chave do evento, como no catálogo. Estável: nunca muda de nome
descricao	O fato em português
versao	Versão do formato do envelope (1)
ocorridoEm	Quando o fato aconteceu, em UTC (ISO-8601)
empresa	A conta da TAI em que o fato aconteceu
dados	Os dados do evento — ids e valores simples, listados no catálogo
registro	Só com Enviar também o registro completo: o registro como a API o devolve (por exemplo, GET /colaborador/{id}). Se a leitura falhar, vem {"indisponivel": "<motivo>"} e o evento segue

Dados sensíveis ficam fora

Os eventos levam ids e valores simples. CPF, salário individual, CID de atestado e respostas de pesquisa anônima nunca vão em dados. Quando precisar de mais, use o registro ou busque pela API com o id.

Cabeçalhos

Cabeçalho	Conteúdo
X-Tai-Evento	A chave do evento (igual a tipo)
X-Tai-Entrega	Id da entrega — igual em todas as tentativas. Use para não processar duas vezes
X-Tai-Tentativa	Número da tentativa (1 na primeira)
X-Tai-Assinatura	t=<segundos>,v1=<hmac> — veja Conferir a assinatura
User-Agent	TAI-Webhooks/1
X-Tai-Teste	true nos envios do botão Testar

Os cabeçalhos que você configurou em Avançado vão junto.

Responder

Responda 2xx assim que receber e processe numa fila sua. O que conta como entregue, quando a TAI tenta de novo e quando desliga o webhook está em Entregas e novas tentativas.

Quando usar um fluxo automatizado em vez do webhook

O webhook envia todo evento assinado, sempre no envelope acima — para tratar só parte deles (“só contas a receber”), filtre no seu sistema pelos dados. Use o bloco Chamar outro sistema de um fluxo automatizado quando precisar:

• de um corpo no formato do seu sistema (por exemplo, o JSON de um incoming webhook do Slack);
• de condições sobre os dados do evento (Só quando);
• de outras ações junto (abrir um card, avisar o gestor).

Em Processos › Fluxos › Novo processo › Fluxo automatizado, comece pelo bloco Quando algo acontece, escolha o evento e acrescente Chamar outro sistema com a URL. Você escolhe método, Cabeçalhos (o token do seu sistema) e o Corpo (JSON), com Inserir informação para usar os dados do evento, como {{gatilho.colaboradorNome}}; vazio, vão todas as informações do fluxo. O envio do fluxo não leva X-Tai-Assinatura: autentique pelos cabeçalhos. Publique o fluxo para ele rodar.