Docs
Páginas desta seção

Guias

Webhooks

Os eventos do workspace que a plataforma envia ao seu sistema, quem recebe cada um, como verificar a assinatura e como iniciar um fluxo a partir do seu sistema.

O que a plataforma envia

Cada evento do registro de eventos pode virar um POST com JSON para um endereço do seu sistema: mensagens que chegam e saem, conversas atribuídas ou finalizadas, leads cadastrados, oportunidades ganhas, campanhas que começam a enviar, e-mails da API de e-mail transacional entregues ou devolvidos. O catálogo completo está em Catálogo de tipos.

Cada requisição é assinada com um segredo que só você e a plataforma conhecem, é repetida quando o seu sistema não confirma o recebimento e fica guardada por 30 dias, com o corpo enviado.

Para o caminho inverso, em que o seu sistema avisa a plataforma, veja Iniciar um fluxo a partir do seu sistema.

Quem recebe cada evento

Um webhook pertence a uma integração, a mesma das chaves de API. Ele recebe só os eventos dos recursos que essa integração pode ler, com as mesmas regras de uma leitura pela API: a permissão de leitura do recurso, os departamentos da integração e a visibilidade das conversas. A tabela de recursos e permissões está em Quem vê cada evento.

Por isso, para receber lead.created, a integração precisa de leads:read; para receber os eventos de uma conversa, de conversations:read e de acesso ao departamento da conversa. Um tipo escolhido que a integração não pode ler nunca chega. As permissões webhooks:* só dizem quem pode cadastrar e alterar os webhooks.

Os e-mails da API de e-mail transacional chegam a quem tem transactional_email:read. Os webhooks cadastrados na tela de e-mail pertencem à integração E-mail transacional, criada para isso, que tem exatamente essa permissão.

Cadastre um webhook

Com a chave de API de uma integração, chame as rotas abaixo: o webhook fica com a integração da chave. Com o login de uma pessoa, informe a integração em integrationId; só quem gerencia os membros do workspace cuida dos webhooks de uma integração. No aplicativo, abra Menu lateral › Integrações › Chaves de API e o botão de webhooks da integração.

RotaO que fazPermissão
GET /v1/webhooks/event-typesO catálogo de tipos e o limite de webhooks.webhooks:read
GET /v1/webhooksLista os webhooks da integração.webhooks:read
POST /v1/webhooksCadastra um webhook e devolve o segredo de assinatura, que começa com whsec_.webhooks:create
PATCH /v1/webhooks/{id}Altera o endereço, os tipos ou pausa e reativa o webhook.webhooks:update
DELETE /v1/webhooks/{id}Remove o webhook e o histórico de entregas dele.webhooks:delete
POST /v1/webhooks/{id}/rotate-secretTroca o segredo. O segredo atual para de assinar na hora.webhooks:update
POST /v1/webhooks/{id}/testEnvia na hora um evento webhook.test assinado.webhooks:update
GET /v1/webhooks/{id}/deliveriesLista as entregas, com o corpo enviado e cada tentativa.webhooks:read
POST /v1/webhooks/{id}/deliveries/{deliveryId}/retryReenvia uma entrega que falhou ou foi pulada.webhooks:update
POST /v1/webhooks/{id}/replay?from=&to=Reenvia as entregas de um período.webhooks:update

Um cadastro:

json
{
  "url": "https://hooks.exemplo.com.br/eventos",
  "events": ["message.received", "lead.created"],
  "enabled": true
}

POST /v1/webhooks aceita o cabeçalho Idempotency-Key: repetir o cadastro com a mesma chave e o mesmo corpo devolve a mesma resposta, sem criar um segundo webhook. Veja Idempotência.

Regras do endereço:

  • Precisa usar https, ter até 2.048 caracteres, sem usuário e senha e sem fragmento (#). Senão, a resposta é 400 com o código webhook_url_invalid.
  • Precisa ser um endereço público da internet. Endereços privados, locais ou reservados são recusados com 422 e o código webhook_url_blocked, e o endereço é conferido de novo a cada entrega.
  • Cada workspace pode ter até 50 webhooks, contando os pausados e os de todas as integrações. Acima disso, 409 com o código webhook_limit_reached.

O tipo campaign.entryStatusUpdated tem volume alto e só chega a quem o escolhe; nenhum tipo chega sem ter sido escolhido.

A requisição

http
POST /seu/endereco HTTP/1.1
Content-Type: application/json
User-Agent: Vozkoia Webhooks
X-Webhook-Id: evt_184467
X-Webhook-Attempt: 1
X-Webhook-Signature: t=1793455512,v1=6b2f0c9e8a7d5b3c1e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d
CabeçalhoDescrição
X-Webhook-IdIdentificador do evento, igual ao campo id do corpo. É o mesmo em todas as tentativas de entrega do evento.
X-Webhook-AttemptNúmero da tentativa, a partir de 1.
X-Webhook-SignatureInstante da assinatura (t, em segundos Unix) e a assinatura (v1).

O corpo é o evento do registro de eventos, no mesmo formato de GET /v1/events:

json
{
  "id": "evt_184467",
  "type": "message.received",
  "seq": 1042,
  "createdAt": "2026-11-04T15:00:00Z",
  "workspaceId": "6b1f0f8e-4a2c-4f7e-9a51-0c3d2b1e7f90",
  "departmentId": "2c9e7b14-5d3a-4e8f-b6a1-7f0e9d2c4b58",
  "data": {
    "messageId": "3c7e9a42-1d5b-4f8e-b0a6-9e2d4c8f1a57",
    "conversationId": "8d3a1f5e-2b9c-4c71-a0e4-6f2d9b7c1e33",
    "channel": "whatsapp",
    "direction": "inbound",
    "messageType": "user_message",
    "text": "Olá, quero saber o preço",
    "mediaId": null,
    "sender": { "kind": "contact", "id": "" },
    "createdAt": "2026-11-04T15:00:00Z"
  }
}
CampoDescrição
idIdentificador do evento. Use para descartar entregas repetidas.
typeUm dos tipos do catálogo.
seqA posição do evento na sequência do workspace.
createdAtQuando a mudança aconteceu, em UTC.
workspaceId, departmentIdO workspace e o departamento do recurso, ou null quando o recurso não tem departamento.
dataOs dados do recurso no momento da mudança. O formato de cada tipo está no guia Eventos.

Um evento de e-mail devolvido:

json
{
  "id": "evt_184470",
  "type": "email.bounced",
  "seq": 1045,
  "createdAt": "2026-10-31T14:05:12Z",
  "workspaceId": "6b1f0f8e-4a2c-4f7e-9a51-0c3d2b1e7f90",
  "departmentId": null,
  "data": {
    "messageId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "sendId": "5a0c6f3e-9d1b-4b7a-8e2f-3c4d5e6f7a8b",
    "idempotencyKey": "recibo-pedido-1234",
    "from": "[email protected]",
    "to": "[email protected]",
    "role": "to",
    "subject": "Recibo do pedido 1234",
    "tags": { "kind": "receipt" },
    "occurredAt": "2026-10-31T14:05:11Z",
    "bounce": { "type": "hard", "subType": "General", "diagnostic": "smtp; 550 5.1.1 user unknown" }
  }
}

O evento de teste tem o tipo webhook.test, seq igual a 0 e, em data, o webhookId e o integrationId. Ele nunca aparece no registro de eventos.

Quem já recebia os eventos de e-mail

Os webhooks da API de e-mail transacional passaram para a integração E-mail transacional com os mesmos endereços, segredos, cabeçalhos e regras de novas tentativas. O corpo passou a ser o evento do registro de eventos:

  • Os campos estão em camelCase: message_id virou data.messageId, occurred_at virou data.occurredAt, created_at virou createdAt, e assim por diante.
  • email.delivery_delayed virou email.deliveryDelayed. Os outros tipos de e-mail mantêm o nome.
  • O corpo ganhou seq, workspaceId e departmentId, e o id passou a ter o formato evt_<número>.

As entregas que já existiam continuam no histórico com o corpo antigo, e um reenvio delas manda esse mesmo corpo.

Verifique a assinatura

Antes de confiar no corpo, confira a assinatura:

  1. Leia t e v1 do cabeçalho X-Webhook-Signature.
  2. Monte o texto t + . + o corpo bruto da requisição, exatamente como chegou, antes de qualquer conversão de JSON.
  3. Calcule o HMAC SHA-256 desse texto usando o segredo completo (incluindo o prefixo whsec_) como chave, e escreva o resultado em hexadecimal minúsculo.
  4. Compare com v1 usando uma comparação de tempo constante.
  5. Recuse eventos com t a mais de 5 minutos do horário atual, para evitar a reutilização de uma requisição antiga.

Node.js

javascript
const crypto = require("node:crypto");

function assinaturaValida(segredo, cabecalho, corpoBruto, toleranciaSegundos = 300) {
  const partes = {};
  for (const parte of cabecalho.split(",")) {
    const [chave, valor] = parte.trim().split("=");
    partes[chave] = valor;
  }
  if (!partes.t || !partes.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(partes.t)) > toleranciaSegundos) return false;
  const esperada = crypto
    .createHmac("sha256", segredo)
    .update(partes.t + ".")
    .update(corpoBruto)
    .digest("hex");
  const recebida = Buffer.from(partes.v1, "utf8");
  const calculada = Buffer.from(esperada, "utf8");
  return recebida.length === calculada.length && crypto.timingSafeEqual(recebida, calculada);
}

No Express, leia o corpo bruto com express.raw({ type: "application/json" }) e passe o Buffer recebido como corpoBruto.

Python

python
import hashlib
import hmac
import time


def assinatura_valida(segredo: str, cabecalho: str, corpo_bruto: bytes, tolerancia: int = 300) -> bool:
    partes = dict(p.strip().split("=", 1) for p in cabecalho.split(",") if "=" in p)
    t, v1 = partes.get("t"), partes.get("v1")
    if not t or not v1 or not t.isdigit():
        return False
    if abs(time.time() - int(t)) > tolerancia:
        return False
    esperada = hmac.new(segredo.encode(), t.encode() + b"." + corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, v1)

Responda rápido com 2xx

Responda com qualquer status 2xx em até 10 segundos para confirmar o recebimento. Qualquer outro status, inclusive um redirecionamento 3xx, um erro de conexão ou a falta de resposta nesse prazo conta como falha.

Uma boa prática é guardar o evento, responder 200 e processar depois, fora da requisição.

Novas tentativas

Sem confirmação, a plataforma tenta de novo depois de 30 segundos, 2 minutos, 10 minutos, 30 minutos, 1 hora, 3 horas e 6 horas. São 8 tentativas no total. Depois da última, a entrega fica como falha e pode ser reenviada pela rota de reenvio ou pela lista de entregas, no aplicativo.

  • São feitas no máximo 4 entregas ao mesmo tempo para o mesmo webhook.
  • Se o endereço falhar por mais de uma hora, quem cuida dos webhooks recebe um aviso. O webhook nunca é pausado sozinho.
  • Um webhook pausado não recebe eventos novos, e as entregas que estavam na fila são puladas. Entregas puladas também podem ser reenviadas.
  • Os webhooks de uma integração desativada param de receber eventos, e as entregas que estavam na fila são puladas.
  • O histórico de entregas, com o corpo de cada uma, fica disponível por 30 dias.

Testar e reenviar

  • POST /v1/webhooks/{id}/test envia um evento webhook.test na hora e devolve a entrega com o resultado da tentativa. O teste aparece na lista de entregas.
  • POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry coloca de novo na fila uma entrega que falhou ou foi pulada.
  • POST /v1/webhooks/{id}/replay?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z coloca de novo na fila as entregas já concluídas do período: entregues, com falha ou puladas. O período tem no máximo 7 dias, dentro dos últimos 30. Cada chamada reenvia até 10.000 entregas; com hasMore igual a true na resposta, chame de novo com o mesmo período.

Para recuperar eventos que nunca viraram entregas, por exemplo de antes de o webhook existir, leia o registro de eventos a partir de um seq.

Repetições e ordem

Um mesmo evento pode chegar mais de uma vez, por exemplo quando a sua resposta se perde e a plataforma tenta de novo, ou quando alguém reenvia a entrega. Use o id do evento (ou o cabeçalho X-Webhook-Id) para processar cada evento uma única vez.

Os eventos também podem chegar fora de ordem. Use o seq para ordenar os eventos de um workspace e data.occurredAt para ordenar os eventos de um mesmo e-mail.

Erros

StatusCódigoQuando
400webhook_url_invalidO endereço não é https, tem usuário e senha ou fragmento.
400webhook_events_invalidNenhum tipo escolhido, ou um tipo que não existe no catálogo.
400webhook_integration_requiredUma pessoa chamou sem integrationId.
400webhook_replay_window_invalidfrom e to faltam, estão invertidos, passam de 7 dias ou saem dos últimos 30 dias.
403webhook_integration_mismatchUma integração tentou cuidar dos webhooks de outra.
403webhook_integration_forbiddenQuem chamou não gerencia os membros do workspace.
404webhook_not_foundO webhook não existe ou não é desta integração.
404webhook_delivery_not_foundA entrega não existe neste webhook.
404integration_not_foundA integração não existe neste workspace.
409webhook_limit_reachedO workspace já tem 50 webhooks.
409webhook_delivery_not_retryableSó entregas que falharam ou foram puladas podem ser reenviadas.
409integration_disabledA integração foi desativada.
422webhook_url_blockedO endereço não é público.

Catálogo de tipos

Esta tabela é gerada a partir do próprio catálogo de eventos da API, o mesmo que valida o campo events de um webhook.

TipoGrupoQuando chega
message.receivedMensagensO contato enviou uma mensagem em qualquer canal.
message.sentMensagensA empresa enviou uma mensagem: pessoa, agente de IA, fluxo, campanha ou integração.
message.statusUpdatedMensagensUma mensagem enviada mudou de situação: entregue, lida ou com falha.
conversation.createdConversasUma conversa nova foi aberta.
conversation.assignedConversasA conversa foi atribuída a um responsável.
conversation.unassignedConversasA conversa ficou sem responsável.
conversation.statusChangedConversasA situação da conversa mudou, incluindo finalizar e reabrir.
conversation.stageChangedConversasA conversa mudou de etapa no funil.
conversation.departmentChangedConversasA conversa foi encaminhada para outro departamento.
lead.createdLeadsUm lead foi cadastrado, à mão, por importação, por integração ou ao chegar por um canal.
lead.updatedLeadsCampos do lead mudaram; data.changedFields lista quais.
lead.anonymizedLeadsOs dados pessoais do lead foram apagados a pedido do titular.
lead.deletedLeadsO lead foi excluído.
opportunity.createdOportunidadesUma oportunidade foi criada.
opportunity.updatedOportunidadesCampos da oportunidade mudaram.
opportunity.stageChangedOportunidadesA oportunidade mudou de etapa no funil.
opportunity.wonOportunidadesA oportunidade foi ganha.
opportunity.lostOportunidadesA oportunidade foi perdida.
campaign.startedCampanhasUma campanha começou a enviar, em qualquer canal.
campaign.pausedCampanhasA campanha foi pausada.
campaign.resumedCampanhasA campanha voltou a enviar depois de uma pausa.
campaign.stoppedCampanhasA campanha foi encerrada antes de terminar.
campaign.completedCampanhasA campanha terminou de enviar.
campaign.entryStatusUpdatedCampanhasUm destinatário da campanha mudou de situação. Volume alto: só chega a quem pedir este tipo.
email.sentE-mailsUm e-mail da API de e-mail transacional foi aceito pelo provedor.
email.deliveredE-mailsO e-mail chegou ao servidor do destinatário.
email.deliveryDelayedE-mailsA entrega do e-mail está atrasada e será tentada de novo.
email.bouncedE-mailsO e-mail voltou.
email.complainedE-mailsO destinatário marcou o e-mail como spam.
email.openedE-mailsO destinatário abriu o e-mail.
email.clickedE-mailsO destinatário clicou em um link do e-mail.
email.failedE-mailsO e-mail não pôde ser enviado.

Iniciar um fluxo a partir do seu sistema

No caminho inverso, o seu sistema pode iniciar um fluxo da plataforma com um POST para a URL pública do gatilho de webhook do fluxo:

text
https://api.vozkoia.com/webhooks/workflow/SEU_TOKEN
  • O gatilho é criado em POST /workflows/{id}/webhook, que devolve a URL (com o token) e, quando o modo exige, o segredo, uma única vez. Um fluxo tem no máximo um gatilho de webhook.
  • A autenticação pode ser só o token da URL (none), um token num cabeçalho (header_token, por padrão X-Webhook-Token) ou uma assinatura HMAC (hmac, por padrão no cabeçalho X-Signature-256).
  • POST /workflows/{id}/webhook/rotate gera um novo token e um novo segredo; a URL antiga para de funcionar.
  • GET /workflows/{id}/webhook/deliveries lista as chamadas recebidas nos últimos 30 dias, com o resultado de cada uma.
  • A URL aceita até 120 chamadas por minuto por endereço IP.

O corpo esperado e as respostas (accepted, duplicate, already_running, ignored) estão no grupo Fluxos da Referência da API.