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.
| Rota | O que faz | Permissão |
|---|---|---|
GET /v1/webhooks/event-types | O catálogo de tipos e o limite de webhooks. | webhooks:read |
GET /v1/webhooks | Lista os webhooks da integração. | webhooks:read |
POST /v1/webhooks | Cadastra 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-secret | Troca o segredo. O segredo atual para de assinar na hora. | webhooks:update |
POST /v1/webhooks/{id}/test | Envia na hora um evento webhook.test assinado. | webhooks:update |
GET /v1/webhooks/{id}/deliveries | Lista as entregas, com o corpo enviado e cada tentativa. | webhooks:read |
POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry | Reenvia 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:
{
"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 é400com o códigowebhook_url_invalid. - Precisa ser um endereço público da internet. Endereços privados, locais ou reservados são recusados com
422e o códigowebhook_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,
409com o códigowebhook_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
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çalho | Descrição |
|---|---|
X-Webhook-Id | Identificador do evento, igual ao campo id do corpo. É o mesmo em todas as tentativas de entrega do evento. |
X-Webhook-Attempt | Número da tentativa, a partir de 1. |
X-Webhook-Signature | Instante 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:
{
"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"
}
}| Campo | Descrição |
|---|---|
id | Identificador do evento. Use para descartar entregas repetidas. |
type | Um dos tipos do catálogo. |
seq | A posição do evento na sequência do workspace. |
createdAt | Quando a mudança aconteceu, em UTC. |
workspaceId, departmentId | O workspace e o departamento do recurso, ou null quando o recurso não tem departamento. |
data | Os dados do recurso no momento da mudança. O formato de cada tipo está no guia Eventos. |
Um evento de e-mail devolvido:
{
"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_idviroudata.messageId,occurred_atviroudata.occurredAt,created_atviroucreatedAt, e assim por diante. email.delivery_delayedvirouemail.deliveryDelayed. Os outros tipos de e-mail mantêm o nome.- O corpo ganhou
seq,workspaceIdedepartmentId, e oidpassou a ter o formatoevt_<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:
- Leia
tev1do cabeçalhoX-Webhook-Signature. - Monte o texto
t+.+ o corpo bruto da requisição, exatamente como chegou, antes de qualquer conversão de JSON. - 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. - Compare com
v1usando uma comparação de tempo constante. - Recuse eventos com
ta mais de 5 minutos do horário atual, para evitar a reutilização de uma requisição antiga.
Node.js
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
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}/testenvia um eventowebhook.testna hora e devolve a entrega com o resultado da tentativa. O teste aparece na lista de entregas.POST /v1/webhooks/{id}/deliveries/{deliveryId}/retrycoloca 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:00Zcoloca 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; comhasMoreigual atruena 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
| Status | Código | Quando |
|---|---|---|
400 | webhook_url_invalid | O endereço não é https, tem usuário e senha ou fragmento. |
400 | webhook_events_invalid | Nenhum tipo escolhido, ou um tipo que não existe no catálogo. |
400 | webhook_integration_required | Uma pessoa chamou sem integrationId. |
400 | webhook_replay_window_invalid | from e to faltam, estão invertidos, passam de 7 dias ou saem dos últimos 30 dias. |
403 | webhook_integration_mismatch | Uma integração tentou cuidar dos webhooks de outra. |
403 | webhook_integration_forbidden | Quem chamou não gerencia os membros do workspace. |
404 | webhook_not_found | O webhook não existe ou não é desta integração. |
404 | webhook_delivery_not_found | A entrega não existe neste webhook. |
404 | integration_not_found | A integração não existe neste workspace. |
409 | webhook_limit_reached | O workspace já tem 50 webhooks. |
409 | webhook_delivery_not_retryable | Só entregas que falharam ou foram puladas podem ser reenviadas. |
409 | integration_disabled | A integração foi desativada. |
422 | webhook_url_blocked | O 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.
| Tipo | Grupo | Quando chega |
|---|---|---|
message.received | Mensagens | O contato enviou uma mensagem em qualquer canal. |
message.sent | Mensagens | A empresa enviou uma mensagem: pessoa, agente de IA, fluxo, campanha ou integração. |
message.statusUpdated | Mensagens | Uma mensagem enviada mudou de situação: entregue, lida ou com falha. |
conversation.created | Conversas | Uma conversa nova foi aberta. |
conversation.assigned | Conversas | A conversa foi atribuída a um responsável. |
conversation.unassigned | Conversas | A conversa ficou sem responsável. |
conversation.statusChanged | Conversas | A situação da conversa mudou, incluindo finalizar e reabrir. |
conversation.stageChanged | Conversas | A conversa mudou de etapa no funil. |
conversation.departmentChanged | Conversas | A conversa foi encaminhada para outro departamento. |
lead.created | Leads | Um lead foi cadastrado, à mão, por importação, por integração ou ao chegar por um canal. |
lead.updated | Leads | Campos do lead mudaram; data.changedFields lista quais. |
lead.anonymized | Leads | Os dados pessoais do lead foram apagados a pedido do titular. |
lead.deleted | Leads | O lead foi excluído. |
opportunity.created | Oportunidades | Uma oportunidade foi criada. |
opportunity.updated | Oportunidades | Campos da oportunidade mudaram. |
opportunity.stageChanged | Oportunidades | A oportunidade mudou de etapa no funil. |
opportunity.won | Oportunidades | A oportunidade foi ganha. |
opportunity.lost | Oportunidades | A oportunidade foi perdida. |
campaign.started | Campanhas | Uma campanha começou a enviar, em qualquer canal. |
campaign.paused | Campanhas | A campanha foi pausada. |
campaign.resumed | Campanhas | A campanha voltou a enviar depois de uma pausa. |
campaign.stopped | Campanhas | A campanha foi encerrada antes de terminar. |
campaign.completed | Campanhas | A campanha terminou de enviar. |
campaign.entryStatusUpdated | Campanhas | Um destinatário da campanha mudou de situação. Volume alto: só chega a quem pedir este tipo. |
email.sent | E-mails | Um e-mail da API de e-mail transacional foi aceito pelo provedor. |
email.delivered | E-mails | O e-mail chegou ao servidor do destinatário. |
email.deliveryDelayed | E-mails | A entrega do e-mail está atrasada e será tentada de novo. |
email.bounced | E-mails | O e-mail voltou. |
email.complained | E-mails | O destinatário marcou o e-mail como spam. |
email.opened | E-mails | O destinatário abriu o e-mail. |
email.clicked | E-mails | O destinatário clicou em um link do e-mail. |
email.failed | E-mails | O 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:
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ãoX-Webhook-Token) ou uma assinatura HMAC (hmac, por padrão no cabeçalhoX-Signature-256). POST /workflows/{id}/webhook/rotategera um novo token e um novo segredo; a URL antiga para de funcionar.GET /workflows/{id}/webhook/deliverieslista 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.