Webhook Payloads

A Tig.ai executa webhook nodes de forma assíncrona depois que a execução de um workflow é concluída. O payload é configurável pelo usuário: você define o template JSON do payload no workflow e pode referenciar as variáveis de contexto da execução.

Como os webhooks funcionam

Uma chamada é concluída (ou uma execução termina)
A Tig.ai executa quaisquer nós webhook do workflow de forma assíncrona
O template do payload é renderizado com o contexto da execução e enviado como um POST JSON (ou o método configurado por você) para o seu endpoint
Respostas diferentes de 200 são registradas, mas não bloqueiam nem fazem retry por padrão (configure retry_config para mudar isso)

Variáveis de contexto do payload

As seguintes variáveis estão disponíveis no seu payload_template usando a sintaxe de chaves duplas (por exemplo {{workflow_run_id}}):

Variável	Tipo	Descrição
`workflow_run_id`	integer	ID da execução concluída
`workflow_run_name`	string	Nome da execução
`workflow_id`	integer	ID do workflow
`workflow_name`	string	Nome do workflow
`call_time`	string	Timestamp ISO-8601 UTC de quando a execução foi criada
`initial_context`	object	Contexto passado quando a chamada foi iniciada
`gathered_context`	object	Dados extraídos durante a chamada pelos nós de agente
`gathered_context.call_disposition`	string	Resultado final da chamada (veja Disposição da chamada)
`cost_info`	object	Detalhamento do custo da chamada
`cost_info.call_duration_seconds`	number	Duração da chamada em segundos
`annotations`	object	Resultados da análise de QA (se um nó `qa` estiver configurado)
`recording_url`	string \| null	URL pública de download da gravação da chamada
`transcript`	array	Transcrição completa da chamada como mensagens com `role`, `timestamp` e `text`
`transcript_url`	string \| null	URL pública de download da transcrição da chamada

Disposição da chamada

O resultado final da chamada está disponível como {{gathered_context.call_disposition}}.

A Tig.ai sempre inclui um campo call_disposition de nível superior no payload entregue. Se o seu template não definir um, ele é adicionado automaticamente a partir de gathered_context.call_disposition; se o seu template o definir explicitamente, o seu valor é mantido.

Exemplo de template de payload

{
  "run_id": "{{workflow_run_id}}",
  "customer": "{{initial_context.customer_name}}",
  "outcome": "{{gathered_context.resolution}}",
  "disposition": "{{gathered_context.call_disposition}}",
  "duration": "{{cost_info.call_duration_seconds}}",
  "recording": "{{recording_url}}"
}

Autenticação

As requisições de webhook suportam os seguintes métodos de autenticação, configurados por meio de uma credencial armazenada:

Tipo	Descrição
`NONE`	Sem autenticação
`API_KEY`	Envia a chave em um cabeçalho personalizado (por exemplo `X-API-Key`)
`BEARER_TOKEN`	Envia `Authorization: Bearer <token>`
`BASIC_AUTH`	Autenticação básica HTTP (usuário + senha)
`CUSTOM_HEADER`	Qualquer par chave-valor de cabeçalho personalizado

Recebendo webhooks

Seu endpoint deve:

Aceitar requisições POST com Content-Type: application/json
Responder rapidamente (dentro de 30 segundos) com um código de status 2xx
Tratar entregas duplicadas de forma idempotente (os retries podem entregar o mesmo payload mais de uma vez)

Exemplo mínimo de receptor (Python)

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook/tig")
async def handle_tig_webhook(request: Request):
    payload = await request.json()
    run_id = payload.get("run_id")
    outcome = payload.get("outcome")
    # process the call result...
    return {"status": "ok"}

Nó de webhook em uma definição de workflow

Consulte Schema de Definição de Workflow para a referência completa de configuração.

{
  "id": "webhook-1",
  "type": "webhook",
  "position": { "x": 600, "y": 0 },
  "data": {
    "name": "Notify CRM",
    "enabled": true,
    "http_method": "POST",
    "endpoint_url": "https://your-service.com/webhook/tig",
    "payload_template": {
      "run_id": "{{workflow_run_id}}",
      "customer": "{{initial_context.customer_name}}",
      "outcome": "{{gathered_context.resolution}}"
    }
  }
}

​Como os webhooks funcionam

​Variáveis de contexto do payload

​Disposição da chamada

​Exemplo de template de payload

​Autenticação

​Recebendo webhooks

​Exemplo mínimo de receptor (Python)

​Nó de webhook em uma definição de workflow

Como os webhooks funcionam

Variáveis de contexto do payload

Disposição da chamada

Exemplo de template de payload

Autenticação

Recebendo webhooks

Exemplo mínimo de receptor (Python)

Nó de webhook em uma definição de workflow