API de Webhooks

A API de Webhooks permite que você assine eventos programaticamente. Use-a para gatilhos instantâneos no estilo Zapier ou integrações personalizadas que precisam de notificações em tempo real.

Observação: A API de Webhooks requer um plano Hobby ou superior com faturamento ativo.

Endpoints

Criar Assinatura

POST /api/v1/webhooks/subscribe

Corpo da Requisição

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Parâmetros

Resposta

Sucesso (201):

{
  "id": "subscription-uuid"
}

Exemplo

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Excluir Assinatura

DELETE /api/v1/webhooks/subscribe/[id]

Resposta

Sucesso (200): Retorna uma resposta vazia com status 200.

Exemplo

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar Agentes

Obtenha os agentes disponíveis para assinar:

GET /api/v1/chatbots

Resposta

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Payload do Webhook

Quando um evento ocorre, enviamos um POST para a sua URL de destino:

Evento de Envio de Formulário

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

Cabeçalhos

Incluímos estes cabeçalhos em cada entrega:

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Verifique a assinatura em relação ao corpo bruto exato da requisição em UTF-8 antes de analisar o JSON. Consulte Segurança de webhooks para o procedimento de assinatura e o catálogo de payloads.

Requisitos de URL

Segurança

Em produção, uma URL de assinatura deve usar HTTPS. Fora da produção, HTTP também é aceito — mas apenas URLs http: e https: são permitidas, e toda URL também deve passar em uma verificação de destino público sobre a própria URL, que rejeita localhost e hostnames de loopback semelhantes, endereços privados e link-local literais, e endpoints de metadados de nuvem.

Consulte Segurança de webhooks para a lista completa de restrições de destino; essa é a descrição canônica desta regra.

Validação

A URL é verificada ao criar a assinatura; URLs que falham nas verificações acima são rejeitadas com um erro 400 cuja mensagem menciona o requisito de produção. A verificação examina a URL exatamente como foi escrita — ela não resolve hostnames, então aponte sua assinatura para o endpoint público onde você realmente pretende receber os eventos. No momento da entrega, o nome do host é resolvido uma única vez, todos os endereços resolvidos devem ser públicos e a conexão é fixada a esses endereços — um nome de host que resolva para um endereço privado ou interno (mesmo que mude entre a resolução e a conexão) nunca é contatado; a tentativa é registrada como target_blocked.

Confiabilidade

Requisitos de Resposta

Seu endpoint deve:

• Retornar status 2xx em até 10 segundos
• Lidar com entregas duplicadas (idempotente)

Tratamento de Falhas

• Entregas com falha são retentadas cinco vezes após a requisição inicial
• Um evento esgotado incrementa a sequência de falhas consecutivas uma vez
• Pelo menos 10 eventos esgotados ao longo de sete dias desabilitam automaticamente uma assinatura
• Os proprietários podem reparar e reativar assinaturas nas configurações de webhook
• A entrega é feita pelo menos uma vez; use eventId para idempotência e não assuma ordenação

Respostas de Erro

Integração com Zapier

Esses endpoints alimentam nossa integração com o Zapier. Quando você conecta o Agentkit ao Zapier:

1. O Zapier chama /api/v1/auth para verificar sua chave de API
2. O Zapier chama /api/v1/chatbots para listar seus agentes
3. Quando você ativa um gatilho, o Zapier chama /api/v1/webhooks/subscribe
4. Os eventos são entregues à URL de webhook do Zapier
5. Quando você desativa, o Zapier chama DELETE na assinatura

Para integrar sem escrever código, use o Zapier diretamente em vez dessas APIs.

Configurar o Zapier →

Exemplo de Código

Gerenciador de Assinaturas em Node.js

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Próximos Passos

• Configure a coleta de leads para gerar eventos
• Configure webhooks na interface para uma configuração pelo painel
• Conecte-se ao Zapier para mais de 5.000 integrações