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
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 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.
| Evento | Quando |
|---|---|
message.received | Mensagem recebida: texto, mídia, localização, contato, resposta de botão ou lista. |
message.sent | Mensagem enviada por você, pelo painel, por bot ou pela API. |
message.status | Entregue, lida ou áudio ouvido (delivered | read | played). Em grupos, um evento por participante. |
message.edited | Mensagem editada. |
message.deleted | Mensagem apagada para todos. |
poll.vote | Alguém votou numa enquete sua (traz o ID da enquete e quem votou; a contagem sai em Resultado da Enquete). |
history.sync | Progresso da importação de histórico após parear ou após Sincronizar Mensagens. |
group.participants | Alguém entrou, saiu, foi promovido ou rebaixado num grupo (add | remove | promote | demote). |
message.reaction | Alguém reagiu a uma mensagem (emoji vazio = reação removida). |
call.received | Chamada de voz ou vídeo recebida (inclusive em grupo). |
call.ended | Chamada terminou: atendida em outro aparelho, recusada, perdida ou encerrada. |
channel.connected | Instância conectou. |
channel.disconnected | Instância caiu ou foi desconectada. |
conversation.mode_changed | Conversa passou de bot para humano ou o contrário. |
conversation.closed | Conversa 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));
}