Webhooks
Os eventos que a plataforma envia ao seu sistema, como verificar a assinatura, e como iniciar um fluxo a partir do seu sistema.
O que a plataforma envia hoje
A plataforma envia webhooks para um único produto: os e-mails enviados pela API de e-mail transacional. Cada evento de um desses e-mails (entrega, devolução, abertura, clique e outros) vira um POST com JSON para o endereço que você cadastrar, assinado com um segredo que só você e a plataforma conhecem.
Mensagens de WhatsApp, conversas, leads, campanhas e os demais recursos ainda não geram webhooks. Para acompanhar esses recursos, use as conexões em tempo real ou consulte a API.
Para o caminho inverso, em que o seu sistema avisa a plataforma, veja Iniciar um fluxo a partir do seu sistema.
Cadastre um webhook
No aplicativo, abra Menu lateral › E-mail e a tela de webhooks da API, ou use as rotas abaixo com o token de login. Listar webhooks e entregas pede a permissão email_marketing:read; as demais rotas pedem email_marketing:configure.
| Rota | O que faz |
|---|---|
GET /email/transactional/webhooks | Lista os webhooks do workspace. |
POST /email/transactional/webhooks | Cadastra um webhook e devolve o segredo de assinatura, que começa com whsec_. |
PATCH /email/transactional/webhooks/{id} | Altera o endereço, os eventos ou pausa e reativa o webhook. |
DELETE /email/transactional/webhooks/{id} | Remove o webhook. |
POST /email/transactional/webhooks/{id}/secret | Troca o segredo. O segredo atual para de assinar na hora. |
GET /email/transactional/webhooks/{id}/deliveries | Lista as entregas, com o resultado de cada tentativa. |
POST /email/transactional/webhooks/{id}/deliveries/{deliveryId}/retry | Reenvia uma entrega que falhou ou foi pulada. |
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ódigoemail_webhook_url_invalid. - Precisa ser um endereço público da internet. Endereços privados, locais ou reservados são recusados com
422e o códigoemail_webhook_url_blocked, e o endereço é conferido de novo a cada entrega. - Cada workspace pode ter até 10 webhooks, contando os pausados. Acima disso,
409com o códigoemail_webhook_limit_reached.
Eventos
| Evento | Quando acontece |
|---|---|
email.sent | O provedor aceitou o e-mail para envio. |
email.delivered | O servidor do destinatário recebeu o e-mail. |
email.delivery_delayed | A entrega está atrasada e o provedor vai tentar de novo. |
email.bounced | O e-mail foi devolvido. |
email.complained | O destinatário marcou o e-mail como spam. |
email.opened | O destinatário abriu o e-mail. |
email.clicked | O destinatário clicou em um link do e-mail. |
email.failed | O provedor recusou o e-mail ou não conseguiu montar a mensagem. |
Aberturas e cliques identificados como automáticos, feitos por robôs, não geram eventos.
A requisição
POST /seu/endereco HTTP/1.1
Content-Type: application/json
User-Agent: Vozko Webhooks
X-Webhook-Id: evt_3f9a1c7e5b2d4086a1e9c3b7d5f20a64
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). |
Corpo de um evento de devolução:
{
"id": "evt_3f9a1c7e5b2d4086a1e9c3b7d5f20a64",
"type": "email.bounced",
"created_at": "2026-10-31T14:05:12Z",
"data": {
"message_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"send_id": "5a0c6f3e-9d1b-4b7a-8e2f-3c4d5e6f7a8b",
"idempotency_key": "recibo-pedido-1234",
"from": "[email protected]",
"to": "[email protected]",
"role": "to",
"subject": "Recibo do pedido 1234",
"tags": {
"kind": "receipt"
},
"occurred_at": "2026-10-31T14:05:11Z",
"bounce": {
"type": "hard",
"sub_type": "General",
"diagnostic": "smtp; 550 5.1.1 user unknown"
}
}
}| Campo | Descrição |
|---|---|
id | Identificador do evento. Use para descartar entregas repetidas. |
type | Um dos eventos da tabela acima. |
created_at | Quando a plataforma registrou o evento, em UTC. |
data.message_id | O id do destinatário na resposta do envio e no registro de envios. |
data.send_id | O id do envio. |
data.idempotency_key | A chave de idempotência usada no envio. |
data.from, data.to, data.role, data.subject | Remetente, destinatário, papel (to, cc ou bcc) e assunto. |
data.tags | As tags informadas no envio. |
data.occurred_at | Quando o evento aconteceu no provedor, em UTC. |
data.bounce | Só em email.bounced: type (hard, soft ou suppressed), sub_type e diagnostic. |
data.complaint | Só em email.complained: feedback_type, quando o provedor informa. |
data.click | Só em email.clicked: link, o endereço clicado. |
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 tem a permissão de configurar o e-mail do workspace 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.
- O histórico de entregas fica disponível por 30 dias.
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 data.occurred_at para ordenar os eventos de um mesmo e-mail.
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.
Updated 17 days ago