API de Webhooks

Webhooks permitem que a plataforma notifique seus outros sistemas no momento em que algo acontece — um novo contato, uma resposta, um agendamento marcado e muito mais. Esta API gerencia as próprias assinaturas: quais URLs recebem quais eventos. Para saber como receber e verificar os payloads que seu endpoint recebe, consulte Webhooks.

Todos os caminhos abaixo são relativos à URL base da API:

https://api.youraiconnector.com/v1

Cada solicitação deve ser autenticada. Consulte Autenticação para os quatro métodos aceitos. Os exemplos aqui usam o cabeçalho X-API-Key (e uma forma de parâmetro de consulta para cURL).

Nota: Webhooks devem estar habilitados para sua conta. Se não estiverem, estes endpoints retornarão um 403.

Como as assinaturas são endereçadas

Cada assinatura tem um id e um name opcional. Qualquer um deles pode ser usado como o {webhookId} no caminho para atualizar, excluir, testar, verificar a integridade e reabilitar.

Prefira o nome. Os IDs de assinatura são posicionais, portanto, podem mudar após a exclusão de outra assinatura. Se você definir um name estável ao criar uma assinatura, enderece-a pelo nome para evitar surpresas.

Listar assinaturas

GET /webhooks

cURL

curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}

signing_enabled e retries_enabled são opções de adesão por assinatura, ambas desativadas a menos que você as ative. Consulte Payloads assinados e Tentativas de reenvio.

apply_to_sub_accounts é a opção de adesão à herança de agência — veja Uma assinatura para todas as contas de cliente. Desativado por padrão e inerte em contas que não possuem contas de cliente.

enabled é o interruptor liga/desliga da assinatura — veja Desativando uma assinatura. Assinaturas desativadas ainda são listadas aqui.

O segredo de assinatura em si nunca é incluído aqui — leia-o a partir de GET /webhooks/{id}/signing-secret.

Listar tipos de eventos assináveis

Retorna as strings exatas que você pode usar em subscribed_to. Use isso para descobrir nomes de eventos válidos em vez de codificá-los diretamente.

GET /webhooks/events

cURL

curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

A resposta é {"success": true, "events": [...]}, onde events atualmente contém 22 strings exatas: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started e Broadcast Completed (Channel Connected é aceito em subscribed_to, mas nada o emite atualmente, então não crie nada baseado nele).

Para saber o que cada evento significa e o código event que ele envia no payload, veja Os 22 Eventos de Webhook. Este endpoint é a lista oficial a qualquer momento — leia-a dinamicamente em vez de codificar os nomes manualmente.

Criar uma assinatura

POST /webhooks

Campo	Obrigatório	Descrição
`url`	Sim	URL HTTPS que receberá os payloads de eventos via `POST`. Deve ser publicamente acessível.
`subscribed_to`	Sim	Um array não vazio de nomes de eventos (veja `/webhooks/events`).
`name`	Não	Um nome de exibição. Também utilizável como `{webhookId}` posteriormente. O padrão é um nome com carimbo de data/hora.
`subscribed_to_tags`	Não	IDs de tags que restringem quais tags produzem uma notificação de resumo de conversa. Isso não limita os eventos da assinatura a essas tags — para receber uma solicitação quando uma tag específica for aplicada, defina uma URL de webhook nessa tag na aba Tags do agente (ou campanha).
`retries_enabled`	Não	Booleano, o padrão é `false`. Opte por tentativas de reenvio de entregas falhas.
`generate_signing_secret`	Não	Booleano, o padrão é `false`. Gere um segredo de assinatura HMAC com a assinatura. O segredo é retornado uma vez, como um `signing_secret` de nível superior na resposta.
`enabled`	Não	Booleano, o padrão é `true`. Passe `false` para criar a assinatura desativada. Veja Desativando uma assinatura.
`apply_to_sub_accounts`	Não	Booleano, o padrão é `false`. Em uma conta de agência, `true` faz com que esta assinatura também receba eventos de todas as contas de cliente — veja Uma assinatura para todas as contas de cliente.

Regras de URL: A URL deve usar https:// e ser acessível publicamente. http:// simples, localhost, endereços de rede privada e endereços internos da plataforma são rejeitados com um 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()

Resposta

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Atualizar uma assinatura

Forneça pelo menos um dos campos url, subscribed_to, name, subscribed_to_tags, retries_enabled, enabled ou apply_to_sub_accounts. Campos omitidos mantêm seus valores atuais. subscribed_to e subscribed_to_tags são substituições, não mesclagens.

PUT /webhooks/{webhookId}

Atualizar uma assinatura nunca altera seu segredo de assinatura — gerencie isso através das rotas de segredo de assinatura.

Quando a URL é alterada, a entrega para a nova URL é reativada automaticamente, dando a um endpoint que falhou anteriormente um novo começo.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'

JavaScript

const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()

Resposta

{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Um id ou nome desconhecido retorna 404 com { "success": false, "error": "Webhook not found" }.

Excluir uma assinatura

Remove a assinatura para que sua URL pare de receber payloads. Seus contadores de integridade de entrega são redefinidos, portanto, adicionar a mesma URL novamente mais tarde começa com um registro limpo.

DELETE /webhooks/{webhookId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true
}

Enviar um payload de teste

Envia um payload de amostra para a URL da assinatura para que você possa verificar seu receptor de ponta a ponta. Opcionalmente, passe um event para controlar qual tipo de evento a amostra simula. Entregas de teste nunca afetam os contadores de integridade da assinatura.

POST /webhooks/{webhookId}/test

A resposta sempre retorna 200 e relata o resultado com um sinalizador delivered — um teste com falha não retorna um status de erro. Quando delivered é false, a resposta inclui os detalhes da falha.

Campo	Obrigatório	Descrição
`event`	Não	Tipo de evento a simular (deve ser um dos `/webhooks/events`). O padrão é um evento de entrega.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()

Resposta (entregue)

{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}

Resposta (falhou)

{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}

failure_type é um de permanent, temporary, timeout, network ou unknown.

Verificar integridade da entrega

Retorna o registro de integridade da entrega para a URL da assinatura: quantas entregas foram bem-sucedidas e falharam, se a entrega está pausada no momento após falhas repetidas e os detalhes da falha mais recente. Retorna "health": null quando nenhuma entrega foi tentada ainda.

GET /webhooks/{webhookId}/health

cURL

curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}

Quando is_disabled é true, a entrega para a URL foi pausada automaticamente após falhas repetidas. Corrija seu receptor e, em seguida, reative-o (abaixo).

Reativar entrega

Resume a entrega para um webhook cuja URL foi pausada automaticamente após falhas repetidas. Isso redefine o sinalizador de pausa e os contadores de falha, mas não tenta uma entrega — use o endpoint de teste posteriormente para confirmar se seu receptor está íntegro novamente.

POST /webhooks/{webhookId}/reenable

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "webhook_id": "0"
}

Desativando uma assinatura

enabled é o próprio interruptor liga/desliga da assinatura. Desativá-lo interrompe as entregas enquanto mantém a URL, a lista de eventos e o segredo de assinatura intactos.

# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Ausente significa ligado. Uma assinatura criada antes da existência deste campo não tem valor enabled armazenado e realiza entregas normalmente. GET /webhooks sempre relata um booleano concreto.
Assinaturas desativadas ainda são listadas por GET /webhooks — é assim que você as encontra para reativá-las.
Uma tentativa de reenvio enfileirada antes da desativação não é retomada: a tentativa de reenvio lê a assinatura novamente no momento do envio e é descartada se ela estiver desativada.
Nada suprimido enquanto desativado é reproduzido quando você a reativa.

Distinto da desativação automática após falhas repetidas, que é relatada por GET /webhooks/{id}/health como is_disabled e limpa com POST /webhooks/{id}/reenable. enabled é o interruptor da conta; is_disabled é o nosso. Nenhum substitui o outro — uma assinatura deve estar ligada e não desativada automaticamente para realizar entregas.

Uma assinatura para todas as contas de cliente (agências)

Em uma conta de agência, defina apply_to_sub_accounts: true em uma assinatura (no momento da criação ou via PUT) e ela também receberá eventos que ocorrem em cada uma das contas de cliente da agência — um único endpoint cobre toda a agência, em vez de recriar a assinatura em cada conta de cliente.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'

Como ele se comporta:

O bloco user diferencia as contas. O bloco user de cada payload identifica a conta em que o evento realmente ocorreu, para que seu receptor possa rotear por cliente.
As próprias configurações da assinatura da agência se aplicam em toda parte. Sua lista de eventos, segredo de assinatura e opção de tentativa de reenvio também são usados para as entregas herdadas.
A própria assinatura de uma conta de cliente para a mesma URL tem prioridade. Se uma conta de cliente tiver sua própria assinatura apontando para a mesma URL, ela será usada para os eventos daquela conta — o mesmo evento nunca é entregue duas vezes para um único endpoint.
Contas de cliente não veem isso. Assinaturas herdadas não aparecem na lista de webhooks da própria conta de cliente, e o cliente não pode desativá-las — apenas a agência as gerencia.
A integridade da entrega é rastreada por conta de cliente. Um endpoint que continua falhando é desativado automaticamente para a conta cujas entregas falharam, não para toda a agência.
subscribed_to_tags não é herdado. A lista de tags faz referência às próprias tags da agência, que não existem nas contas de cliente — a restrição de resumo de conversa aplica-se apenas aos eventos da própria agência.
Inerte em outros lugares. Em uma conta sem contas de cliente, o sinalizador é armazenado corretamente e não faz nada.

Cabeçalhos em cada entrega

Estes três cabeçalhos são enviados em cada entrega, independentemente de a assinatura estar assinada ou não:

Cabeçalho	Significado
`X-Webhook-Delivery`	ID estável para o evento lógico. Idêntico entre tentativas de reenvio — use para deduplicação.
`X-Webhook-Attempt`	Número da tentativa (base 1).
`X-Webhook-Event`	O nome do evento.

Payloads assinados

A assinatura é opcional, desativada por padrão e definida por assinatura. Quando uma assinatura possui um segredo de assinatura, cada entrega carrega dois cabeçalhos adicionais além dos três enviados em cada entrega (X-Webhook-Delivery, X-Webhook-Attempt e X-Webhook-Event):

Cabeçalho	Significado
`X-Webhook-Signature`	`v1=<hex>` — HMAC-SHA256 da string `"<timestamp>.<raw request body>"`, codificada com o segredo de assinatura por webhook que você gera e rotaciona em `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`.
`X-Webhook-Timestamp`	Horário de envio, em segundos Unix. Vinculado à assinatura, portanto, não pode ser alterado independentemente.

Para verificar, recalcule o HMAC-SHA256 sobre o corpo bruto com seu segredo e compare-o com o cabeçalho. Verifique em relação ao corpo da solicitação bruto. A re-serialização do JSON analisado altera os bytes e quebra a comparação. Rejeite entregas cujo carimbo de data/hora esteja fora de uma janela de validade (300s é um padrão razoável) para evitar repetição, e compare com uma função de tempo constante (timing-safe).

Consulte Payloads assinados para exemplos completos de verificação em Node e Python.

Assinatura não é o mesmo que autenticação de API. A API REST em si autentica com chaves de API em vez de OAuth (OAuth 2.1 existe para servidores MCP que você registra como ferramentas de bot), e ainda não existem pacotes SDK oficiais para npm ou PyPI — chame os endpoints com qualquer cliente HTTP.

Ler o segredo de assinatura

GET /webhooks/{id}/signing-secret

curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}

Quando a assinatura está desativada, signing_enabled é false e signing_secret é null.

Gerar ou rotacionar o segredo de assinatura

POST /webhooks/{id}/signing-secret

Cria um segredo (ativando a assinatura) ou substitui o existente. Retorna o novo segredo.

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}

A rotação entra em vigor imediatamente — a próxima entrega é assinada apenas com o novo segredo. Aceite ambos os segredos brevemente enquanto você implementa a alteração em um endpoint ativo.

Você também pode gerar um segredo no momento da criação passando "generate_signing_secret": true para POST /webhooks; a resposta então inclui um campo signing_secret de nível superior.

Desativar assinatura

DELETE /webhooks/{id}/signing-secret

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}

Todas as três rotas de segredo de assinatura exigem a permissão de edição de Integrações, incluindo GET — o segredo é uma credencial que pode forjar entregas, portanto, não é exposto a funções somente leitura.

Novas tentativas

Opcional, desativado por padrão e definido por assinatura através do booleano retries_enabled em POST /webhooks ou PUT /webhooks/{id}.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'

Quando ativado, uma entrega com falha é tentada novamente em 1m, 5m, 30m e 2h após a primeira tentativa (cerca de 2h40m de cobertura).

Tentado novamente: respostas 5xx, timeouts e falhas de conexão.
Não tentado novamente: qualquer 4xx. O receptor está rejeitando a própria solicitação, portanto, repeti-la sem alterações apenas reproduz a rejeição.

As tentativas tornam possível a entrega duplicada — um endpoint que processou um evento, mas expirou antes de responder, o verá novamente. Use X-Webhook-Delivery para deduplicação, que é constante em todas as tentativas. É por isso que as tentativas são opcionais.

Os contadores de delivery-health contam uma entrega completa, não cada tentativa: uma falha é registrada apenas uma vez quando todas as tentativas são esgotadas, portanto, ativar as novas tentativas não faz com que o gatilho de desativação automática ocorra mais cedo.

Erros

Todos os erros usam o envelope padrão:

{
  "success": false,
  "error": "Webhook not found"
}

Casos comuns: uma URL que não é permitida, um subscribed_to vazio/inválido ou campos ausentes retornam 400; um id ou nome desconhecido retorna 404; e um 403 significa que webhooks não estão habilitados para sua conta. Veja Erros para a lista completa.

Próximos passos

Webhooks (recebendo payloads) — configure seu receptor e entenda o formato do payload.
Autenticação — as quatro maneiras de autenticar uma solicitação.
Erros e Limites de Taxa — códigos de status e o limite de 300 req/min.

API de Webhooks #

Como as assinaturas são endereçadas #

Listar assinaturas #

Listar tipos de eventos assináveis #

Criar uma assinatura #

Atualizar uma assinatura #

Excluir uma assinatura #

Enviar um payload de teste #

Verificar integridade da entrega #

Reativar entrega #

Desativando uma assinatura #

Uma assinatura para todas as contas de cliente (agências) #

Cabeçalhos em cada entrega #

Payloads assinados #

Ler o segredo de assinatura #

Gerar ou rotacionar o segredo de assinatura #

Desativar assinatura #

Novas tentativas #

Erros #

Próximos passos #

API de Webhooks

Como as assinaturas são endereçadas

Listar assinaturas

Listar tipos de eventos assináveis

Criar uma assinatura

Atualizar uma assinatura

Excluir uma assinatura

Enviar um payload de teste

Verificar integridade da entrega

Reativar entrega

Desativando uma assinatura

Uma assinatura para todas as contas de cliente (agências)

Cabeçalhos em cada entrega

Payloads assinados

Ler o segredo de assinatura

Gerar ou rotacionar o segredo de assinatura

Desativar assinatura

Novas tentativas

Erros

Próximos passos