Webhooks

​

Como funciona

1. Você cria uma rota https no seu servidor para receber os eventos. Em geral, uma rota por integração.
2. Você cadastra essa URL no portal de webhooks do Spark e escolhe os eventos que quer receber.
3. A cada evento, sua rota verifica a assinatura, responde 2xx rápido e processa o evento em fila, se precisar de mais tempo.

​

Cadastrar uma URL

​

Formato da requisição

{
  "event": "chats.created",
  "data": {
    "tenantId": "tenant_…",
    "chatId": "chat_…",
    "platform": "whatsapp",
    "entrypointId": "wa_entrypoint_…",
    "occurredAt": "2026-05-08T12:00:00.000Z"
  }
}

​

Eventos disponíveis

​

Campos por evento

• tenantId, chatId e occurredAt (ISO 8601).
• chat: resumo do chat (id, platform, kind, entrypointId, name, status e outros).
• message: a mensagem completa (texto, tipo, status, mídia, localização, remetente, dados de modelo e outros).
• Só em messages.received: entrypointId, o canal que recebeu a mensagem.
• Só em messages.sent: source, a origem do envio. Valores: public_api, user, automation, campaign, addon, integration, business_hours, business_app e system. business_app indica mensagem enviada pelo app WhatsApp Business num número em coexistência.

• tenantId, chatId, occurredAt e platform (whatsapp, whatsapp_lite, instagram, telegram ou lead_form).
• entrypointId, quando o chat pertence a um canal.
• acquisition, quando o lead veio do Meta Lead Ads: source (meta_lead_ads), commercialChannel, capturedAt e meta, com os IDs de página, formulário, campanha, conjunto de anúncios e anúncio.

• tenantId, sessionId e occurredAt.
• Em connected: entrypoint, com o mesmo formato da consulta da sessão.
• Em connection_failed: status (failed ou expired) e reason.

• tenantId, entrypointId, occurredAt, importedChats e importedMessages.
• As mensagens e os chats importados não geram messages.received, messages.sent nem chats.created.

• tenantId, occurredAt e template, no mesmo formato de GET /v1/message-templates/{id}.
• Trate cada evento como um upsert pelo template.id. Em deleted, apague a cópia local.
• Um status DELETED vindo da Meta chega como status_updated e não remove o modelo do Spark.
• Alterações feitas pela própria API também geram eventos, para que outros sistemas da organização fiquem sincronizados.

​

Responder à entrega

​

Retentativas e eventos repetidos

​

Verificação de assinatura

• Use o corpo bruto da requisição, exatamente como chegou. Ler o JSON e serializar de novo invalida a assinatura.
• Passe os cabeçalhos svix-id, svix-timestamp e svix-signature e o segredo do endpoint (whsec_…) para a classe Webhook do pacote svix ou para a biblioteca equivalente na sua linguagem.

import { Webhook } from "svix";

const wh = new Webhook(process.env.SPARK_WEBHOOK_SECRET!);

export async function POST(req: Request) {
  const payload = await req.text();
  const event = wh.verify(payload, {
    "svix-id": req.headers.get("svix-id")!,
    "svix-timestamp": req.headers.get("svix-timestamp")!,
    "svix-signature": req.headers.get("svix-signature")!,
  });

  // processe o evento ou coloque-o numa fila
  return new Response(null, { status: 200 });
}

​

Tipos para o seu código

• x-webhooks: uma entrada por evento (messages.received e os demais), com o corpo e exemplos.
• components.schemas: os tipos de cada corpo, como SparkWebhookBodyMessagesReceived e MessagesReceivedWebhookPayload.

• Usar os tipos do SDK sparkcrm, como SparkWebhookBody. Veja TypeScript: webhooks e tipos.
• Gerar tipos com Orval, openapi-typescript ou outra ferramenta a partir da especificação.
• Ver os exemplos de cada evento no catálogo do portal de webhooks.

​

Leitura adicional

• Introdução ao recebimento de webhooks, do Svix.
• Como verificar webhooks, do Svix.