> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tigyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Payloads

> Variáveis de contexto disponíveis nos nós de webhook e os dados que a Tig.ai envia após uma chamada

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

1. Uma chamada é concluída (ou uma execução termina)
2. A Tig.ai executa quaisquer nós `webhook` do workflow de forma assíncrona
3. 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
4. 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](#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}}`.

<Note>
  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.
</Note>

### Exemplo de template de payload

```json theme={null}
{
  "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)

```python theme={null}
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](/pt/developer/workflow-schema#nó-webhook) para a referência completa de configuração.

```json theme={null}
{
  "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}}"
    }
  }
}
```