Webhooks

Quando você chama o endpoint Chat informando webhook_url, a API opera em modo assíncrono: em vez de manter a conexão aberta enquanto o agente processa, a API retorna 202 Accepted na hora e envia o resultado para a URL do webhook assim que o processamento termina.

Use webhooks para não bloquear sua aplicação enquanto a IA pensa — ideal para integrações via n8n, Make, Zapier ou qualquer backend que não queira lidar com long-polling.

O fluxo assíncrono

1. Você chama POST /chat/{agentId} com webhook_url no body (e opcionalmente metadata).
2. A API responde imediatamente com 202 Accepted, devolvendo conversation_id e message_id. O status é "processing".
3. Quando o agente termina, a API faz um POST para a sua webhook_url com o WebhookPayload completo.

curl -X POST https://api.squados.io/v1/chat/{agentId} \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual o status do pedido #1234?",
    "webhook_url": "https://sua-app.com/webhooks/squados",
    "metadata": {
      "crm_ticket_id": "TKT-9981",
      "customer_email": "cliente@exemplo.com"
    }
  }'

Resposta 202:

{
  "success": true,
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "status": "processing"
}

Payload do webhook

Quando o processamento termina, seu endpoint recebe um POST com o seguinte schema:

Campo	Tipo	Descrição
event	string	Tipo do evento: message.completed, message.received ou message.error
agent_id	uuid	ID do agente que processou a mensagem
conversation_id	uuid	ID da conversa (o mesmo do 202)
message_id	uuid	ID da mensagem (o mesmo do 202)
response	string	Resposta gerada pelo agente. Presente em message.completed
error	string	Descrição do erro. Presente em message.error
model	string	Modelo LLM usado na geração
credits_used	number	Créditos consumidos pelo processamento
metadata	object	O objeto metadata que você enviou na requisição original, ecoado intacto
timestamp	date-time	Momento em que o evento foi gerado (ISO 8601)

Exemplo de payload message.completed:

{
  "event": "message.completed",
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "response": "O pedido #1234 está em separação no estoque e a previsão de despacho é amanhã.",
  "model": "gpt-4o-mini",
  "credits_used": 3,
  "metadata": {
    "crm_ticket_id": "TKT-9981",
    "customer_email": "cliente@exemplo.com"
  },
  "timestamp": "2026-06-08T14:32:07Z"
}

Eventos possíveis

Evento	Quando ocorre
message.completed	O agente terminou de gerar a resposta com sucesso
message.received	A mensagem foi recebida e está na fila (notificação intermediária)
message.error	Ocorreu um erro durante o processamento

Correlação com metadata

O objeto metadata que você enviou no request original é ecoado intacto no campo metadata do webhook. Use isso para casar a resposta do agente com o registro de origem no seu sistema — ticket de suporte, lead do CRM, pedido de e-commerce, qualquer coisa.

Exemplo: request com metadata de CRM

curl -X POST https://api.squados.io/v1/chat/{agentId} \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Resuma o histórico deste cliente.",
    "webhook_url": "https://sua-app.com/webhooks/squados",
    "metadata": {
      "crm_ticket_id": "TKT-9981",
      "customer_email": "cliente@exemplo.com"
    }
  }'

Webhook recebido:

{
  "event": "message.completed",
  "response": "O cliente tem 3 compras nos últimos 6 meses, nenhuma reclamação aberta...",
  "metadata": {
    "crm_ticket_id": "TKT-9981",
    "customer_email": "cliente@exemplo.com"
  },
  "timestamp": "2026-06-08T14:32:07Z"
}

Dica

Use metadata para passar qualquer identificador do seu sistema — ID de ticket, ID de conversa no seu CRM, ID do pedido, e-mail do cliente. Você recebe exatamente o que enviou, sem transformação, então qualquer chave que facilite o roteamento no seu handler é válida.

Respondendo ao webhook

Seu endpoint deve responder com um status 2xx (200, 201 ou 204) logo após receber o payload — sem processamento pesado dentro do handler. A API interpreta qualquer resposta não-2xx como falha de entrega.

// Resposta mínima aceita (corpo pode ser vazio)
HTTP/1.1 200 OK

Cuidado

Mantenha o handler de webhook leve: receba, persista ou enfileire, e responda 200 imediatamente. Processamento demorado dentro do handler pode causar timeout e a API pode retentar a entrega.

Para erros e códigos de status da API, consulte a referência de Erros.