Um webhook envia uma requisição HTTPS do Mateflow para uma URL que você controla sempre que algo acontece na sua comunidade, como a entrada de um novo membro ou a chegada de um pagamento. Use webhooks para manter um CRM, uma ferramenta de e-mail ou o seu próprio app sincronizados. Você os configura em Admin → Configurações → Integrações → Webhooks.
Quem pode fazer isso: proprietários e administradores. · Onde: web (console de administração). · Plano: os webhooks, e quantos você pode criar, dependem do seu plano da plataforma. Se o seu plano deixar de incluí-los, as entregas param. Seus webhooks são mantidos e voltam a funcionar quando você faz upgrade.
Criar um endpoint de webhook
- Acesse Admin → Configurações → Integrações e abra a aba Webhooks.
- Clique em Adicionar Webhook.
- Informe Nome e uma URL do Endpoint HTTPS.
- Se desejar, gere um segredo de assinatura e copie para o receptor. Veja a verificação abaixo.
- Selecione explicitamente pelo menos um evento. Busque ou escolha por categoria; Documentação do evento abre a referência.
- Clique em Criar Webhook. Novos webhooks são salvos inativos.
- Salve, envie um teste e ative quando o receptor estiver pronto.
Se o botão Adicionar Webhook mostrar um aviso de upgrade, o seu plano não inclui webhooks ou você atingiu o limite de webhooks do plano. Veja Verificar o uso e os limites do plano.
Eventos de webhook que você pode assinar
| Categoria | Eventos |
|---|---|
| Membros | Membro Ingressou, Membro Saiu, Função Alterada, Membro Suspenso (também enviado para banimentos), Membro Reintegrado, Membro Adicionado ao Grupo de Acesso, Membro Removido do Grupo de Acesso |
| Conteúdo | Publicação Criada, Comentário Criado, Publicação Excluída, Comentário Excluído |
| Pagamentos | Pagamento Recebido, Pagamento com Falha, Assinatura Criada, Assinatura Renovada, Assinatura Cancelada, Reembolso Emitido |
Webhooks mais antigos podem mostrar eventos que não estão mais disponíveis. Você pode removê-los, mas não pode adicioná-los de novo.
Em configurações antigas, uma lista vazia significa todos os eventos. Mantenha-a ou escolha assinaturas explícitas. Eventos indisponíveis permanecem ao editar outros ajustes; para mudar assinaturas, remova os não compatíveis e escolha pelo menos um atual. Se o catálogo não carregar, tente novamente antes de selecionar ou testar.
Como funcionam os eventos de webhook de grupos de acesso
Membro Adicionado ao Grupo de Acesso e Membro Removido do Grupo de Acesso (os grupos de acesso antes se chamavam níveis de membro) são disparados quando os grupos de um membro realmente mudam. Cada evento cobre um membro e um grupo e inclui o nome de usuário e o e-mail do membro, o nome do grupo e o que causou a mudança: um administrador, uma assinatura, um convite, o grupo de acesso padrão ou um grupo excluído.
- Nenhum evento de grupo de acesso é enviado antes de Membro Ingressou, então o grupo padrão de um membro novo no cadastro não é anunciado, nem as mudanças enquanto um membro aguarda aprovação.
- Excluir um grupo de acesso envia um evento de remoção para cada membro que o tinha. Esses eventos, e os que vêm da definição de um grupo padrão, podem chegar alguns minutos depois.
- Remover um grupo concedido por uma assinatura envia uma remoção e depois uma adição, porque a assinatura o adiciona de volta na hora. Veja Adicionar ou remover o grupo de acesso de um membro.
Como funciona o evento de webhook "Membro Saiu"
Membro Saiu é enviado uma vez quando alguém deixa de ser membro da sua comunidade, para que você possa removê-lo do seu CRM ou da sua lista de e-mails. Ele é disparado quando:
- um administrador usa Remover da comunidade ou Anonimizar membro;
- o membro exclui a própria conta. Uma exclusão agendada conta quando termina o período de espera de 30 dias, não quando ele pede; se ele cancelar, nada é enviado;
- a sua política de retenção de dados apaga um membro inativo. Ela roda toda noite, então muitos eventos podem chegar de uma vez.
Cada evento inclui o nome de usuário e o e-mail do membro de antes da saída, mesmo que a conta tenha sido anonimizada, para que você o encontre no seu próprio sistema. Ele também informa como o membro saiu e, quando um administrador o removeu ou anonimizou, qual administrador. Se o administrador escreveu uma Nota interna (opcional) ao remover o membro, a nota também é incluída.
Membro Saiu não é enviado quando um membro desativa a conta, é suspenso ou banido (nesse caso, é Membro Suspenso), sai de um espaço ou nunca terminou de entrar. Os grupos de acesso que um membro que sai tinha não enviam Membro Removido do Grupo de Acesso.
Apps conectados cujo cartão mostra Enviando todos os eventos passam a enviar Membro Saiu também, inclusive para canais do Slack ou do Discord. Para deixá-lo de fora, escolha Editar configurações e selecione os eventos a enviar. Veja Visão geral das integrações: API, webhooks e Zapier.
Verificar as assinaturas dos webhooks com o segredo de assinatura
Quando um webhook tem um segredo, o Mateflow assina cada requisição com HMAC-SHA256 para que o seu servidor possa conferir que ela veio do Mateflow e não foi alterada (verificação de assinatura). Cada requisição traz dois cabeçalhos:
X-Mateflow-Timestamp: quando a requisição foi enviada, em segundos Unix.X-Mateflow-Signature:sha256=seguido da assinatura codificada em hexadecimal.
Para verificar uma requisição no seu servidor:
- Leia o corpo bruto da requisição exatamente como foi recebido, antes de interpretar o JSON.
- Monte a string assinada: o valor de
X-Mateflow-Timestamp, um ponto (.) e depois o corpo bruto. - Calcule um HMAC-SHA256 dessa string, usando o seu segredo como chave, e codifique-o em hexadecimal.
- Compare-o com a parte de
X-Mateflow-Signaturedepois desha256=, usando uma comparação de tempo constante. Rejeite a requisição se forem diferentes. - Se quiser, rejeite requisições com um timestamp de mais de alguns minutos atrás, para bloquear repetições (replays).
As requisições da ação Disparar webhook de uma regra de automação são assinadas da mesma forma quando a regra tem um segredo. Veja Automatizar tarefas com regras.
Depois que você salva, o segredo fica oculto. Para mantê-lo, deixe o campo em branco ao editar o webhook. Para trocá-lo, gere um novo e atualize o seu servidor ao mesmo tempo.
Testar, pausar, editar ou excluir um webhook
Salve antes de testar ou abrir os logs. Nas ações, abra o teste, escolha um evento assinado compatível com amostras e clique em Enviar teste. A amostra tem test=true e vai para a URL salva, mesmo com o webhook inativo. O receptor deve reconhecer testes. Um 2xx confirma apenas recebimento HTTP, não a conclusão do seu processo. Confira status, resposta e logs.
Ative após testar; desativar pausa entregas reais. Editar um webhook ativo vale imediatamente ao salvar. Excluir remove também os logs permanentemente. Se a configuração mudar, o teste anterior expira: teste novamente a versão salva.
Conferir as entregas e as novas tentativas dos webhooks
Abra a aba Logs de Entrega para ver cada requisição, com o Status HTTP, a Duração e a Origem. Para ver as entregas de um webhook, use Filtrar por webhook. Clique em Exibir Detalhes para ver o Payload da Requisição e o Corpo da Resposta completos. Os logs de entrega são mantidos por 30 dias.
Quando uma entrega falha, o Mateflow tenta de novo automaticamente depois de 1 minuto, 10 minutos, 1 hora e 6 horas. As respostas HTTP 429 e 408 também são repetidas; as outras respostas 4xx não são. Quando as tentativas acabam, ou em um 4xx que não é repetido, o proprietário e os administradores recebem um e-mail, no máximo uma vez por dia para cada webhook.
Para enviar uma entrega de novo você mesmo, clique em Reenviar na linha dela. O mesmo corpo é enviado, assinado de novo, para a URL atual do webhook. Atualize a página para ver o resultado como uma nova linha. Um webhook excluído ou desativado não pode reenviar. Cada tentativa ganha uma linha própria. Uma nova tentativa automática recebe um novo ID da entrega, Reenviar mantém o original e o ID do evento continua o mesmo; então as linhas que compartilham um ID do evento são tentativas de um mesmo evento. As entregas podem chegar mais de uma vez ou fora de ordem, então faça o seu servidor eliminar duplicatas pelo ID do evento. Para os campos do payload e exemplos de código, clique em Abrir documentação no cartão Referência de webhooks para desenvolvedores da aba Webhooks ou acesse mateflow.com/developers/webhooks. Você pode enviar esse link para a sua equipe de desenvolvimento.
Os logs filtram por evento, resultado, webhook, datas, Fonte e Plataforma. As métricas seguem o escopo e período e contam tentativas HTTP com testes e reenvios, não eventos únicos. A página mostra histórico disponível e retenção. Os totais de configuração são uma visão separada de webhooks ativos, inativos e ativos com falhas recentes.
Artigos relacionados
Este guia foi útil?