v2PainelCriar chave

Eventos e webhooks

Receba os eventos do workspace por HTTP POST, assinados com HMAC-SHA256, com novas tentativas e reenvio manual.

POSTDefinir URL de eventos

/webhook/set/:instance

Cria ou atualiza o webhook desta instância: ela recebe só os próprios eventos. O segredo HMAC volta apenas na criação. Webhooks do workspace (painel) continuam recebendo tudo.

urlstringObrigatório
URL http(s) pública do seu servidor.
enabledbooleanOpcional
Liga ou desliga a entrega (padrão true).
eventsstring[]Opcional
Nomes do ConnectDM ou da Evolution (MESSAGES_UPSERT, MESSAGES_UPDATE, CONNECTION_UPDATE, GROUP_PARTICIPANTS_UPDATE, CALL…). Vazio = todos.
headersobjectOpcional
Até 20 cabeçalhos extras (só com https). x-centralizer-*, content-type e host são reservados.
curl -X POST https://api.connectdm.app/webhook/set/loja \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://seu-app.com/webhooks/connect",
  "events": [
    "MESSAGES_UPSERT",
    "MESSAGES_UPDATE"
  ],
  "headers": {
    "Authorization": "Bearer meu-token"
  }
}'

GETVer configuração de eventos

/webhook/find/:instance

Webhook desta instância (sem o segredo), ou null.

curl -X GET https://api.connectdm.app/webhook/find/loja \
  -H "apikey: sk_live_SUA_CHAVE"

Lista de eventos

Todo evento chega como POST JSON com os cabeçalhos x-centralizer-event, x-centralizer-event-id, x-centralizer-delivery, x-centralizer-attempt e x-centralizer-signature. Webhooks com lista de eventos salvos antes de message.reaction e call.ended existirem só passam a recebê-los depois de salvos de novo.

EventoQuando
message.receivedMensagem recebida: texto, mídia, localização, contato, resposta de botão ou lista.
message.sentMensagem enviada por você, pelo painel, por bot ou pela API.
message.statusEntregue, lida ou áudio ouvido (delivered | read | played). Em grupos, um evento por participante.
message.editedMensagem editada.
message.deletedMensagem apagada para todos.
poll.voteAlguém votou numa enquete sua (traz o ID da enquete e quem votou; a contagem sai em Resultado da Enquete).
history.syncProgresso da importação de histórico após parear ou após Sincronizar Mensagens.
group.participantsAlguém entrou, saiu, foi promovido ou rebaixado num grupo (add | remove | promote | demote).
message.reactionAlguém reagiu a uma mensagem (emoji vazio = reação removida).
call.receivedChamada de voz ou vídeo recebida (inclusive em grupo).
call.endedChamada terminou: atendida em outro aparelho, recusada, perdida ou encerrada.
channel.connectedInstância conectou.
channel.disconnectedInstância caiu ou foi desconectada.
conversation.mode_changedConversa passou de bot para humano ou o contrário.
conversation.closedConversa encerrada.

Assinatura e reenvio

x-centralizer-signature vem como t=<unix>,v1=<hmac>, onde v1 = hex(HMAC_SHA256(segredo, "<t>.<corpo bruto>")). Compare em tempo constante e recuse t com mais de 5 minutos de diferença.

Respostas 2xx contam como entregues. Timeout, 408, 429 e 5xx são tentados de novo 6 vezes (0 s, 30 s, 2 min, 10 min, 30 min, 2 h). Use x-centralizer-event-id para descartar duplicados.

import crypto from 'node:crypto';

export function verify(secret, rawBody, header) {
  const {t, v1} = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mac = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}
© 2026 ConnectDM by Centralizer · Referência da API