Em duas linhas: um webhook avisa outra ferramenta toda vez que algo acontece no MB Suite: entra um lead, um negócio muda de etapa, sai uma publicação. Você o cria em Configurações > API e MCP, na aba Webhooks: escolhe o endereço e os eventos, e o MB Suite os envia assinados, tenta de novo se o seu destino não responder e guarda o registro de cada entrega.

Para que serve um webhook?

Sem webhooks, para que outro sistema fique sabendo de um lead novo, alguém precisa copiá-lo à mão ou essa ferramenta precisa ficar consultando o MB Suite toda hora. Com um webhook é o contrário: assim que o evento acontece, o MB Suite envia os dados para o endereço que você informou. Assim, cada lead que entra pelos seus formulários ou anúncios chega ao seu ERP ou à sua planilha, cada negócio que avança de etapa dispara o fluxo que você montou no Make e cada publicação que sai pode ficar registrada onde a sua equipe a acompanha, exceto o que os termos de uma plataforma não deixam enviar para um webhook (veja abaixo).

Os webhooks deste artigo saem do MB Suite. Se você procura o contrário —que outra ferramenta envie leads para o seu CRM—, isso se configura com uma fonte de leads Webhook genérico: veja Conectar formulários e anúncios, e saber de qual campanha veio cada lead.

Quem pode criar webhooks?

Só o owner e os admins do workspace —ou da Conta, se o webhook for de uma Conta— veem a aba Webhooks de API e MCP; o resto da equipe vê só MCP e Documentação. Para criá-los, a API e o MCP precisam estar habilitados no workspace. Se alguém os desligou, os webhooks param de enviar eventos novos e Criar webhook fica desabilitado até que sejam habilitados de novo; o que já estava na fila espera até 72 horas (veja API, MCP e webhooks). Os webhooks de um workspace também podem escutar as suas Contas; os de uma Conta escutam só o que acontece nela. Cada organização pode ter ao mesmo tempo tantos webhooks ativos quanto o plano dela permitir: o contador acima da tabela mostra quantos você tem sobre o máximo, e as cotas de cada plano estão em Preços.

Um webhook depende de quem o criou: se essa pessoa sair da organização ou deixar de ser owner ou admin, o webhook é desativado e os owners e admins recebem um aviso nas notificações. Na tabela ele aparece como Desativado, com o motivo ao passar o cursor, e qualquer owner ou admin pode reativá-lo.

Como crio um webhook?

Vá em Configurações > API e MCP e abra a aba Webhooks.
Pressione Criar webhook.
Em URL de destino, cole o endereço que a sua ferramenta forneceu. Ele precisa começar com https:// e ser público: o MB Suite o verifica enquanto você digita e, se servir, mostra Destino válido com o nome do servidor; se não, o campo diz por quê. Endereços privados ou internos não são aceitos.
Se quiser, escreva uma Descrição para lembrar para que serve (por exemplo, «Leads para o Odoo»).
Em Eventos, marque os que você quer receber. No topo há uma busca; abaixo, os eventos agrupados por área, com o CRM primeiro, e cada área e cada módulo têm a sua caixa para marcar todos. Cada evento traz a sua descrição e Ver exemplo, que mostra como ele chega, com dados de exemplo. Todos os eventos marca os de todos os módulos de uma vez: marque só os de que você precisa.
Se você está em um workspace e também quer os eventos das suas Contas, ative Escutar também as Contas e escolha Todas as Contas (inclui as que você criar depois) ou Escolher Contas. Cada evento traz em org_id a organização onde aconteceu, para você saber de qual Conta ele vem.
Se o seu destino precisar, abra Avançado (mais abaixo, o que tem lá).
Pressione Criar webhook. O segredo de assinatura aparece na mesma janela: copie-o com Copiar, guarde-o e feche com Pronto, que é habilitado quando você o copia ou marca Já guardei.

O segredo —começa com whsec_— é mostrado uma única vez e não pode ser visto de novo. Guarde-o onde o seu sistema guarda os segredos dele, não em um documento compartilhado. Se você o perder, use Rotacionar segredo para obter um novo.

O que tem em Avançado?

Formato: Completo (recomendado) envia o registro inteiro —o negócio, a pessoa, a empresa— e é o mais prático para o Make ou o Odoo; Somente IDs envia só os identificadores, e o seu sistema consulta o restante. Se um evento completo passar de 256 KB, ele chega só com IDs, com truncated: true dentro de data.

Versão da API: deixe como vem. Cada entrega a informa no cabeçalho MB-Api-Version.

Cabeçalhos fixos: até 5 pares de nome e valor que viajam em cada entrega, para destinos que exigem um token próprio. Os valores não são mostrados de novo: ao editar o webhook você vê só os nomes, e para trocá-los usa Substituir cabeçalhos. Eles não podem substituir os cabeçalhos que o MB Suite define (os que aparecem mais abaixo).

Como testo um webhook?

No menu Ações da linha (os três pontos), escolha Enviar evento de teste. Um evento webhook.test chega ao seu destino, assinado e com os mesmos cabeçalhos de um real, e você o vê em Ver entregas. Serve para conferir que o seu sistema o recebe e que a sua verificação da assinatura funciona. O evento de teste chega mesmo com o webhook desativado: assim você pode testar o seu destino antes de reativá-lo. Enquanto a API e o MCP estão desligados, nada sai, nem o evento de teste nem um reenvio.

O evento de teste traz uma mensagem curta, não um lead nem um negócio. Para ver o formato real de um evento sem mexer nos seus dados, use a organização de prática: quando o seu workspace a tem (ela é criada com a primeira API key de teste, veja API keys), acima da tabela aparece o seletor Produção / Teste. Em Teste você cria os webhooks da organização de prática: eles recebem só os eventos do que as API keys de teste fazem e são entregues de verdade, com a mesma assinatura.

Sem a organização de prática, você também pode provocar um evento real: cadastre um prospecto à mão ou mude um negócio de etapa.

Quais eventos posso receber?

Há eventos de quase todos os módulos do MB Suite. Cada um diz na sua descrição quando é disparado —alguns só quando a mudança chega pela API, pelo MCP ou pela MIA—, então leia-a antes de montar o seu fluxo. Estes são os do CRM, os mais usados, e o que dispara cada um:

Evento	Quando chega
`crm.lead.created`	Entra um lead novo: por uma fonte de leads (o seu formulário do MB Suite, um anúncio com formulário da Meta, a sua página de agendamentos, o webhook genérico ou uma mensagem direta ou um comentário do Instagram ou do Facebook que entra no CRM), com a primeira mensagem de WhatsApp de um contato novo, pela API, ou porque alguém cadastrou um prospecto à mão. Traz a pessoa, o prospecto ou o negócio em que ele se converteu e a fonte. Também chega para alguém que já estava no CRM, desde que o lead crie um prospecto ou um negócio novo para essa pessoa. Não chega quando nada novo é criado: o mesmo lead enviado de novo, uma fonte configurada em Ignorar duplicado ou um lead que vai para o prospecto ou o negócio que a pessoa já tinha. Ainda não chega com uma mensagem ou um comentário das redes de um perfil que já está vinculado a uma pessoa. Também não chega com os leads do Google Ads, do TikTok ou do LinkedIn (os formulários deles, e as mensagens diretas e os comentários do TikTok): os termos dessas plataformas não deixam enviar os seus dados para um webhook.
`crm.deal.created`	Um negócio é criado: à mão no CRM, pela API, ao converter um prospecto em negócio (pela tela, pela API ou pelo Setter de IA) ou quando uma fonte de leads envia o lead direto para um pipeline. Neste último caso também chega `crm.lead.created`, com o negócio dentro.
`crm.deal.stage_changed`	Um negócio passa para outra etapa ou outro pipeline: pela tela, em uma movimentação em massa ou por uma sequência. Traz a etapa e o pipeline novos e, em `previous`, os anteriores, com os nomes. As movimentações feitas por uma mesclagem ou pela exclusão de uma etapa não o disparam.
`crm.deal.won`	Um negócio é marcado como ganho. `previous_status` diz em que status ele estava.
`crm.deal.lost`	Um negócio é marcado como perdido, com o motivo de perda, se algum foi escolhido.
`crm.deal.reopened`	Um negócio ganho ou perdido volta a ficar aberto.
`crm.deal.archived`	Um negócio é arquivado (`archived: true`) ou desarquivado (`archived: false`) pela ficha dele ou pela API. Arquivá-lo junto com uma pessoa ou uma empresa não o dispara.
`crm.deal.updated`	Outros dados de um negócio são editados: título, valor, responsável, empresa, etiquetas, campos personalizados… `changed_fields` diz quais. Uma etapa nova, ganhar, perder, reabrir ou arquivar enviam o próprio evento, não este, e as mudanças de etiquetas ou de responsável em massa não o disparam.
`crm.deal.deleted`	Um negócio é excluído, um a um ou vários de uma vez. Traz a última cópia do negócio, que fica 30 dias na Lixeira do CRM. Excluí-lo junto com os registros vinculados, ou mesclá-lo, não o dispara.
`crm.person.created`	Alguém cria uma pessoa no CRM, ou ela é criada pela API. Uma pessoa que chega como lead novo por uma fonte é enviada como `crm.lead.created`, e as importações não o disparam.
`crm.person.updated`	Alguém edita os dados de uma pessoa pela ficha dela ou pela API. `changed_fields` diz o que mudou. As mudanças em massa não o disparam.
`crm.person.deleted`	Uma pessoa é excluída, uma a uma ou várias de uma vez; ela fica 30 dias na Lixeira. Excluí-la junto com os registros vinculados, ou mesclá-la, não o dispara.
`crm.company.created`	Alguém cria uma empresa no CRM, ou ela é criada pela API. As empresas que uma fonte de leads ou uma importação cria não o disparam.
`crm.company.updated`	Alguém edita os dados de uma empresa pela ficha dela ou pela API. `changed_fields` diz o que mudou. As mudanças em massa não o disparam.
`crm.company.deleted`	Uma empresa é excluída, uma a uma ou várias de uma vez; ela fica 30 dias na Lixeira. Excluí-la junto com os registros vinculados, ou mesclá-la, não o dispara.
`crm.activity.created`	Alguém registra uma atividade —nota, tarefa, ligação, reunião ou resposta— em um negócio, uma pessoa, uma empresa ou um prospecto, no CRM ou pela API. O que é registrado sozinho (e-mails sincronizados de uma caixa, mensagens de WhatsApp ou das redes, e o que as sequências, o discador ou a Equipe IA registram) não o dispara.
`webhook.test`	Só quando você pressiona Enviar evento de teste, e só para esse webhook.

Também não chega nenhum evento de um negócio ou de uma pessoa que entrou por um formulário do Google Ads, pelo TikTok ou pelo LinkedIn —nem quando o negócio é criado, muda de etapa ou é ganho—, nem de uma pessoa ou de uma empresa que foi criada ou completada pelo TikTok ou pelo LinkedIn: como com crm.lead.created, os termos dessas plataformas não deixam enviar os seus dados para um webhook. As empresas criadas ou completadas com um formulário do Google Ads, e as pessoas completadas com um, chegam sem as respostas do formulário nos campos personalizados. E em todos os eventos do CRM, uma atribuição ao Google Ads, ao LinkedIn ou ao TikTok chega com os ids, sem os nomes da campanha, do grupo, do anúncio e do formulário (nem a palavra-chave do Google), e as pessoas e as empresas chegam sem o link do LinkedIn.

O que é excluído pode ser recuperado durante esses 30 dias na Lixeira do CRM. E um webhook recebe o que acontece a partir do momento em que você o cria —pode levar até um minuto para começar— e não traz o histórico de antes.

Se você trouxer leads históricos com o backfill de uma fonte de leads, cada lead que cria um prospecto ou um negócio novo, mesmo que a pessoa já estivesse no CRM, também é enviado como crm.lead.created. Leve isso em conta antes de rodá-lo: o seu destino recebe um evento para cada lead que cria algo novo; um duplicado não envia nada. O backfill de uma fonte do Google Ads ou do LinkedIn não o envia, assim como o resto dos leads dessas plataformas.

Alguns exemplos de outros módulos:

Evento	Quando chega
`web_forms.submission.received`	Um formulário web publicado recebe uma resposta real. Traz o que foi enviado, o lead do CRM que ele criou se o formulário estiver vinculado a uma fonte de leads e a atribuição de anúncios. As respostas que os filtros de spam descartam e os envios de teste pelo editor não o disparam.
`social_planner.post.published`	Uma publicação saiu em todas as redes, na hora ou no horário programado. Traz o link quando a rede o fornece. Não chega com uma publicação que vai para o LinkedIn, o TikTok ou o Google Business, mesmo que também vá para outras redes: os termos deles não deixam enviar os seus dados para um webhook.
`social_planner.post.failed`	Uma publicação não pôde ser publicada em nenhuma rede depois das novas tentativas automáticas, com o motivo em cada rede. Como o anterior, não chega com uma publicação que vai para o LinkedIn, o TikTok ou o Google Business.
`social_inbox.item.received`	Chega ao Inbox um comentário, uma mensagem direta ou uma menção do Instagram ou do Facebook (os do LinkedIn e do TikTok não o disparam: os termos deles não deixam enviar os seus dados para um webhook). As mensagens diretas que pertencem ao CRM e o que é classificado como spam não o disparam.
`email_marketing.campaign.sent`	Sai uma campanha de e-mail —pela tela, pela API ou no horário programado—, com quantas mensagens ficaram na fila.
`task_management.comment.added`	Alguém comenta uma tarefa, pelo app, pela API, pelo MCP ou pela MIA. Os comentários em tarefas privadas não o disparam.
`reports.pdf.ready`	Terminou de ser gerado o PDF de um relatório, pela tela de Relatórios ou pela API. O evento não traz o arquivo: ele é baixado pela API, a menos que o relatório tenha blocos de uma plataforma cujos termos não permitem isso (veja API, MCP e webhooks).
`alerts.alert.triggered`	A avaliação de cada hora encontra que a condição de um alerta de métrica foi atendida, uma vez por disparo. Não chega com um alerta sobre uma métrica do Google Ads, do Business Profile, do LinkedIn, do TikTok ou do YouTube: os termos deles não deixam enviar os seus dados para um webhook.

Nos outros módulos, um evento com dados do Google Ads, do Business Profile, do LinkedIn, do TikTok ou do YouTube também não chega, ou chega sem esses dados: por exemplo, uma alteração em uma das contas de anúncios deles, um envio cujos PDFs incluem as contas deles, uma conexão do LinkedIn ou do TikTok que é desconectada ou o gasto de um plano de mídia. Os eventos que só trazem esses dados, como os do SEO Local ou do Auto-Budget, ou a sincronização de custos de um plano de mídia, não são oferecidos. Se um webhook já estava inscrito em um deles, o evento continua na lista dele, mas não chega, e uma nova tentativa ou um reenvio de um evento com esses dados também não sai: a entrega fica como Cancelada.

A lista completa, com um exemplo de cada evento, está no seletor (Ver exemplo) e na referência de eventos de webhooks da documentação.

O que o meu sistema recebe e o que ele precisa responder?

Cada entrega é um POST com Content-Type: application/json. O corpo tem sempre o mesmo formato: id (o do evento, evt_…), type, created_at, api_version, org_id e data, com os dados do evento em snake_case. Os cabeçalhos trazem MB-Signature (a assinatura), MB-Event-Id, MB-Event-Type, MB-Webhook-Id, MB-Delivery-Id, MB-Api-Version, Idempotency-Key e um User-Agent que começa com MB-Suite-Webhooks.

O seu sistema precisa responder com um código 2xx em menos de 10 segundos. Se ele tiver muito a fazer, que responda primeiro e processe depois. Qualquer outra resposta, um redirecionamento (3xx) ou passar dos 10 segundos conta como falha e é tentado de novo.

Um mesmo evento pode chegar mais de uma vez: por exemplo, se o seu sistema o processou mas respondeu tarde, ou se você o reenviar. Use o id dele —que também viaja em Idempotency-Key— para não processá-lo duas vezes.

Como verifico que o evento vem do MB Suite?

Cada entrega viaja assinada no cabeçalho MB-Signature, com este formato: t=1762000000,v1=5257a8…. t é o momento da assinatura, em segundos Unix, e v1 é um HMAC-SHA256 em hexadecimal, calculado com o seu segredo sobre t, um ponto e o corpo exato do request.

Leia o corpo do request exatamente como chegou, sem convertê-lo antes em JSON: se você o converter e montar de novo, a assinatura deixa de bater.
Separe t e os valores v1 do cabeçalho.
Calcule o HMAC-SHA256 de t.corpo com o seu segredo e compare-o com cada v1 usando uma comparação de tempo constante. Se algum bater, o evento vem do MB Suite.
Descarte o evento se t estiver a mais de 5 minutos da sua hora atual: assim ninguém consegue reenviar para você uma entrega antiga.

Não é preciso escrevê-lo do zero: abaixo do segredo, Verificar a assinatura no seu servidor traz o código pronto para Node, Python e PHP. Enquanto um segredo está sendo rotacionado, o cabeçalho traz dois v1=, e vale qualquer um dos dois.

Como conecto com o Make, o Odoo ou o Monday?

Make. Crie um cenário que comece com o módulo «Custom webhook»: o Make fornece uma URL, que você cola em URL de destino. Depois clique em «Re-determine data structure» no Make e use Enviar evento de teste para que ele aprenda o envelope; para o formato real de um lead ou de um negócio, provoque o evento. O Make responde 200 assim que recebe, então a entrega aparece como Entregue mesmo que o cenário falhe depois. Como trava, o mais simples é um cabeçalho fixo (por exemplo, X-Make-Token com um valor longo que você inventar) e um filtro no cenário que o compare.

Odoo. Nas versões recentes, uma regra de automação com o gatilho «On webhook» fornece uma URL para colar em URL de destino. Para criar o lead, a ação precisa ser de código Python («Execute Code»), que recebe o JSON em payload: o nome, por exemplo, está em payload['data']['person']['full_name'], e payload['id'] ajuda a não criar o mesmo lead duas vezes. Como a ação recebe o JSON já lido, verificar a assinatura ali não é prático: trate a URL do Odoo como um segredo e não a compartilhe.

Monday. O Monday não recebe webhooks de outros sistemas por conta própria. O caminho mais direto é colocar o Make no meio: um cenário que começa com o webhook do MB Suite e segue com o módulo do Monday que cria o item no seu quadro, com os campos de data (por exemplo, data.person.full_name, data.deal.title ou data.stage.name). Também há apps no marketplace do Monday que recebem webhooks.

O que acontece se o meu sistema não responder?

O MB Suite tenta de novo cada entrega que falha, com esperas cada vez mais longas entre uma tentativa e a seguinte: 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas e, a partir daí, a cada 12 horas, até 11 tentativas em cerca de 72 horas. Quando uma tentativa dá certo, essa entrega fica como Entregue e não é enviada de novo.

Se o seu destino passar 24 horas sem responder bem, o owner e os admins recebem um e-mail, e a tabela mostra abaixo do endereço «Sem responder desde…», com o tempo que está falhando, e que ele se desativa sozinho após 72 horas. Se após 72 horas ele continuar falhando, o webhook passa para Desativado por falhas: deixa de receber eventos, as entregas na fila são canceladas e chegam outro e-mail e um aviso nas notificações.

Se todos os seus webhooks pararem de entregar ao mesmo tempo, o problema pode estar do nosso lado: confira developers.mb-suite.com/status, que mostra o status da API, do servidor MCP e dos webhooks, com os incidentes em andamento e as manutenções programadas. Confira também se ninguém desligou a API e o MCP do workspace e se a assinatura dele continua paga e ativa.

Como reativo e recupero o que não chegou?

Corrija o que estava falhando no seu destino. Em Ver entregas você tem o código e a resposta de cada tentativa.
No menu Ações do webhook, escolha Reativar.
Deixe marcado Reenviar o que falhou antes de ser desativado —ele vem marcado— e confirme com Reativar.
O webhook volta a receber os eventos novos e, se você marcou o reenvio, as entregas que falharam ou foram canceladas nas 72 horas anteriores à desativação voltam para a fila, uma única vez cada, da mais antiga para a mais nova. A mensagem de confirmação diz quantas foram reenviadas.

O que acontece no MB Suite enquanto um webhook está desativado —por falhas ou porque você o desativou— não fica guardado para esse webhook, então não pode ser reenviado depois. Ao reativá-lo, ele recebe a partir desse momento.

Como vejo o que foi enviado e reenvio uma entrega?

No menu Ações do webhook, escolha Ver entregas. Abre o painel Entregas com as últimas 100, da mais nova para a mais antiga.
Cada linha mostra o status (Pendente, Tentando de novo, Entregue, Falhou ou Cancelada), o evento, a tentativa (por exemplo, Tentativa 3/11), quanto tempo levou e o código que o seu destino respondeu. Filtre com Todas, Falhas, Entregues ou Pendentes.
Abra uma entrega para ver o detalhe: cada tentativa com o resultado, a Requisição enviada (cabeçalhos e corpo) e a Última resposta do seu destino, até os primeiros 4 KB. A assinatura e os valores dos seus cabeçalhos fixos não são mostrados.
Para enviá-la de novo, pressione Reenviar: sai uma entrega nova do mesmo evento, marcada Reenvio, com a própria série de novas tentativas. O webhook precisa estar ativo.

Os eventos e as entregas ficam guardados por 30 dias.

Como troco o segredo sem interromper a integração?

No menu Ações do webhook, escolha Rotacionar segredo.
Confirme com Rotacionar. Aparece o Segredo novo: copie-o e guarde-o, como o primeiro.
Troque-o no seu sistema. Durante 24 horas, cada entrega leva duas assinaturas v1= —uma com o segredo novo e outra com o anterior— e vale qualquer uma; passado esse prazo, só o novo assina.

O que mais posso fazer com um webhook?

No menu Ações da linha: Editar muda o endereço (ele é verificado de novo), a descrição, os eventos, as Contas ou o que está em Avançado, sem mexer no segredo; Desativar coloca o webhook em pausa —ele deixa de receber eventos e as entregas na fila são canceladas— até você reativá-lo; Excluir apaga o webhook e o segredo, cancela o que estava na fila e não pode ser desfeito. Tudo isso funciona também enquanto a API e o MCP estão desligados.

Um webhook leva dados dos seus contatos —nomes, e-mails, telefones— do MB Suite para o sistema que você escolher. Assine só os eventos de que você precisa e envie-os para destinos que você controla. O uso dos webhooks e o tratamento desses dados são regidos pelos nossos Termos e Condições e pelo nosso Acordo de Processamento de Dados (DPA). Próximo passo: Integrações: o que você pode conectar e como funcionam.

Ainda tem dúvidas?

Pergunte à MIA, o assistente de IA do MB Suite: abra-o com o botão MB AI (⌘J) na barra superior. A MIA conhece a seção em que você está, então você pode consultá-la sobre o que vê na tela e também tirar dúvidas de como usar o MB Suite.

Webhooks: avise as suas outras ferramentas no momento em que algo acontece no MB Suite