Webhooks

Envie eventos assinados em tempo real para serviços externos.

Webhooks enviam notificações assinadas quando leads, formulários, conversas ou escalonamentos mudam. Eles exigem um plano Hobby ou superior com faturamento ativo.

Configure um endpoint

Abra Configurações → Webhooks de um agente, escolha um ou mais eventos, informe um endpoint público HTTPS e crie as assinaturas. O Agentkit mantém um único segredo de assinatura para todas as linhas de eventos no mesmo endpoint. Os proprietários da conta podem revelar ou rotacionar esse segredo a partir do cartão do endpoint.

Os nomes de eventos suportados são:

lead_created
form_submission (alias legado de lead)
custom_form_submitted
conversation_started
conversation_ended
escalation_created

conversation_ended é emitido após 30 minutos sem uma mensagem. Sua transcrição é um snapshot imutável de, no máximo, 200 mensagens, com cada mensagem limitada a 2.000 caracteres. Conversas apenas no Playground e conversas sem mensagens de usuário não são despachadas. A análise da transcrição atualmente é null.

Envelope

Todo evento usa o mesmo envelope estável:

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Use o eventId como sua chave de idempotência. A entrega é feita ao menos uma vez e a ordenação não é garantida. O mesmo ID de evento, timestamp de ocorrência e bytes JSON são reutilizados nas novas tentativas.

Verifique as assinaturas

As entregas incluem:

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Leia o corpo da requisição como texto UTF-8 bruto. Analise t e v1, calcule o HMAC-SHA256 com o segredo do endpoint sobre os bytes exatos de t + "." + rawBody, e compare os digests com uma função de tempo constante. Não analise e reserialize o JSON antes da verificação. Rejeite timestamps expirados de acordo com sua política de replay.

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Confiabilidade e resultados

Retorne um status 2xx dentro de 10 segundos. Uma resposta não 2xx, timeout ou erro de rede é tentado novamente cinco vezes após a requisição inicial (normalmente seis tentativas no total) com backoff do QStash. A página de configurações mostra os últimos 20 resultados finais.

Um evento esgotado incrementa a sequência de falhas uma única vez, independentemente do número de tentativas ou de callbacks duplicados. Uma assinatura é desativada automaticamente somente após pelo menos 10 eventos esgotados consecutivos abrangendo pelo menos sete dias. Os proprietários recebem uma notificação que permite nova tentativa e podem reativá-la após a correção. Um evento bem-sucedido reinicia a sequência.

As URLs de endpoint devem usar HTTP ou HTTPS, devem ser públicas e não podem apontar para localhost, faixas de IP privadas/link-local, ou endpoints de metadados de nuvem. Em produção, HTTPS é obrigatório. No momento da entrega, o Agentkit resolve o nome do host uma única vez, exige que todos os endereços resolvidos sejam públicos e fixa a conexão a esses endereços, de modo que o DNS rebinding não consegue redirecionar uma entrega para um endereço interno.

Ativação da programação

O código de verificação de conversas ociosas é enviado desativado. Um operador pode revisar e executar pnpm --filter chatbots setup:idle-conversation-webhooks após a implantação. O comando cria a programação de 15 minutos no QStash; o merge do código não a cria nem a ativa.