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.

RotaO que faz
GET /email/transactional/webhooksLista os webhooks do workspace.
POST /email/transactional/webhooksCadastra 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}/secretTroca o segredo. O segredo atual para de assinar na hora.
GET /email/transactional/webhooks/{id}/deliveriesLista as entregas, com o resultado de cada tentativa.
POST /email/transactional/webhooks/{id}/deliveries/{deliveryId}/retryReenvia 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 é 400 com o código email_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 email_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, 409 com o código email_webhook_limit_reached.

Eventos

EventoQuando acontece
email.sentO provedor aceitou o e-mail para envio.
email.deliveredO servidor do destinatário recebeu o e-mail.
email.delivery_delayedA entrega está atrasada e o provedor vai tentar de novo.
email.bouncedO e-mail foi devolvido.
email.complainedO destinatário marcou o e-mail como spam.
email.openedO destinatário abriu o e-mail.
email.clickedO destinatário clicou em um link do e-mail.
email.failedO 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ç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).

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"
    }
  }
}
CampoDescrição
idIdentificador do evento. Use para descartar entregas repetidas.
typeUm dos eventos da tabela acima.
created_atQuando a plataforma registrou o evento, em UTC.
data.message_idO id do destinatário na resposta do envio e no registro de envios.
data.send_idO id do envio.
data.idempotency_keyA chave de idempotência usada no envio.
data.from, data.to, data.role, data.subjectRemetente, destinatário, papel (to, cc ou bcc) e assunto.
data.tagsAs tags informadas no envio.
data.occurred_atQuando o evento aconteceu no provedor, em UTC.
data.bounceSó em email.bounced: type (hard, soft ou suppressed), sub_type e diagnostic.
data.complaintSó em email.complained: feedback_type, quando o provedor informa.
data.clickSó em email.clicked: link, o endereço clicado.

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

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ã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.


Did this page help you?