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.
Criar um endpoint de webhook
- Acesse Admin → Configurações → Integrações e abra a aba Webhooks.
- Clique em Adicionar Webhook.
- Informe um Nome (com menos de 100 caracteres) e a URL do Endpoint. A URL precisa usar HTTPS.
- Opcional, mas recomendado: em Secret (opcional), clique no botão de gerar (Gerar secret) e copie o segredo para o seu servidor. Veja a seção sobre assinaturas abaixo.
- Em Eventos, marque os eventos que serão enviados. Marque o nome de uma categoria para selecionar todos os eventos dela.
- Deixe Ativo ligado para que o webhook comece a receber eventos.
- Clique em Criar Webhook.
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, 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.
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.
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).
Durante um período de transição, as requisições também trazem o próprio segredo em um cabeçalho X-Webhook-Secret. Verifique a assinatura em vez de confiar nesse cabeçalho.
As requisições da ação Disparar webhook de uma regra de automação funcionam de outro jeito: elas não são assinadas, e o segredo da regra é enviado como está no cabeçalho X-Webhook-Secret. 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
No menu Ações do webhook:
- Testar Webhook envia uma requisição de teste para o seu endpoint.
- Desativar interrompe as entregas sem excluir o webhook; Ativar o liga de novo.
- Editar altera o nome, a URL, o segredo ou os eventos.
- Excluir remove o webhook e todos os logs de entrega dele. Isso não pode ser desfeito.
A lista mostra o Status, o Último Acionamento e as contagens de Sucesso e Falhou de cada webhook. Um webhook mostra um status de erro quando as entregas recentes falharam.
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. 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, até 3 vezes. Não há botão para você reenviar uma entrega. Cada tentativa ganha uma linha própria e um novo ID da entrega, enquanto 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, veja a documentação para desenvolvedores em mateflow.com/developers.
Artigos relacionados
Este guia foi útil?