Webhooks

Um webhook é a Memberfy a chamar o seu sistema: quando alguém entra, compra, subscreve, se inscreve num evento ou conclui um curso, a Memberfy envia um POST para o URL que registou, assinado, de imediato. É o caminho inverso da API, em que é o seu sistema que pergunta.

Quem cria o webhook é o proprietário ou um administrador da comunidade, em Definições › Integrações e APIs, separador Webhooks. Ver Integrações & APIs › Webhooks. Este guia é para quem escreve o código que recebe.

#O que chega

Um POST por evento e por webhook, com Content-Type: application/json; charset=utf-8 e User-Agent: Memberfy-Webhooks/1. O corpo é sempre o mesmo envelope:

{
  "id": "evt_01JAB3K7Q9X2M4N6P8R0S2T4V6",
  "type": "purchase.completed",
  "version": 1,
  "occurredAt": "2026-10-19T14:03:11.402Z",
  "community": { "id": "c3f1a2b4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "slug": "apicon" },
  "data": {
    "member": { "id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "name": "Maria Souza", "email": "[email protected]", "phone": "+5541999998888", "phoneCountry": "BR" },
    "purchaseId": "…",
    "product": { "id": "…", "name": "Plano Pro", "type": "SUBSCRIPTION" },
    "amount": { "amount": 9990, "currency": "BRL" }
  }
}

Os valores em dinheiro vêm em cêntimos, como { "amount": 9990, "currency": "BRL" }, sempre o que a pessoa pagou. A pessoa envolvida vem em data.member, com id, name, email, phone (no formato E.164, como +5541999998888, ou null) e phoneCountry (o país do telefone em ISO 3166-1 alfa-2, como BR, ou null).

#Os eventos

São 97 eventos em 27 famílias, mais o ping:

O webhook subscreve eventos um a um ou a família inteira (member.*); quem marca a família recebe também os eventos que nela entrarem depois. Os campos de cada um estão em Eventos de webhook.

Um convite ainda não aceite não gera member.joined.

#Níveis e pontos

member.level_changed sai quando o nível da pessoa muda:

{
  "member": { "id": "…", "name": "Maria Souza", "email": "[email protected]" },
  "direction": "down",
  "cause": "activity",
  "from": { "id": "…", "level": 5, "name": "Kernel" },
  "to": { "id": "…", "level": 4, "name": "Shell" },
  "points": 640
}

• direction: up (subiu, de imediato) ou down (desceu).
• cause: points (os pontos mudaram o nível) ou activity (os requisitos da semana: cumpridos, na subida, ou não cumpridos na semana anterior, na descida de segunda-feira às 00:00 no fuso horário da comunidade).
• from e to: o nível antes e depois, com id, level (o número, 1 é o primeiro) e name. O id vem null enquanto a comunidade usa os níveis predefinidos sem nunca os ter aberto.
• Saltar vários níveis de uma vez gera um evento, com o nível final em to.

member.points_changed sai quando o total de pontos da pessoa na comunidade muda: from, to, delta e source (action, uma ação da pessoa; reversal, pontos devolvidos porque a ação foi desfeita; team, um ajuste da equipa; workflow, um ajuste de workflow).

Nenhum dos dois sai num recálculo de pontos, numa importação, quando a comunidade muda os níveis ou com a gamificação desligada.

#O que nunca vai

Nenhum evento leva taxa, valor líquido, dados do processador de pagamento ou do cartão, CPF/CNPJ do registo, morada, data de nascimento, campos personalizados, palavra-passe, token ou segredo, IP, nem o texto de publicações, comentários e pedidos de suporte. As respostas de um formulário (form.submitted) e das perguntas da inscrição de um evento (event.registered) vão como a pessoa as preencheu, incluindo o campo Documento. O nome, o e-mail e o telefone da pessoa (quando o registou) vão sempre: por isso o ecrã avisa, ao criar o webhook, que seguem dados pessoais para o destino.

#Verificar a assinatura

Toda a entrega vai assinada no padrão Standard Webhooks, com o segredo do webhook (começa por whsec_ e aparece uma única vez, na criação ou ao rodar). Três cabeçalhos:

Verifique sempre antes de confiar no conteúdo, com o corpo exatamente como chegou (sem fazer o parse antes), e recuse um webhook-timestamp com mais de 5 minutos de diferença do seu relógio. A biblioteca standardwebhooks faz as duas coisas. Em Node, com Express:

import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const webhook = new Webhook(process.env.MEMBERFY_WEBHOOK_SECRET); // whsec_…

// O corpo cru: a assinatura é sobre os bytes que chegaram.
app.post('/memberfy', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body.toString('utf8'), {
      'webhook-id': req.get('webhook-id'),
      'webhook-timestamp': req.get('webhook-timestamp'),
      'webhook-signature': req.get('webhook-signature'),
    });
  } catch {
    return res.status(400).send('invalid signature');
  }

  if (await alreadyProcessed(event.id)) return res.sendStatus(200); // deduplicar
  res.sendStatus(200); // responda logo e processe depois
  await queue.add(event); // ex.: a sua fila de trabalho
});

app.listen(3000);

O verify verifica a assinatura e a hora e devolve o envelope já lido. Existem bibliotecas do mesmo padrão para Python, Go, Ruby, PHP, Java e outras linguagens.

Ao rodar o segredo, o novo vale de imediato e o antigo deixa de valer: atualize o seu lado logo a seguir.

#Responder e processar

• Responda com qualquer 2xx em até 10 segundos. Passado esse tempo, a tentativa conta como falha.
• Processe depois de responder (uma fila, um job): uma integração lenta não pode atrasar a resposta.
• Desduplique pelo webhook-id. O mesmo evento pode chegar mais de uma vez (uma resposta que se perdeu na rede, um reenvio pelo ecrã): guarde os ids já processados e ignore o repetido.
• A ordem não é garantida. Um subscription.renewed pode chegar antes do subscription.created que ficou em nova tentativa. Use o occurredAt para ordenar e, quando precisar do estado atual, pergunte à API.
• Os redirecionamentos não são seguidos: um 301 ou 302 conta como falha. Registe o URL final.

#Novas tentativas

Sem um 2xx, a Memberfy tenta de novo. São até 8 tentativas por entrega: a primeira de imediato e as outras ao fim de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h, cerca de 45 horas no total. Esgotadas as 8, a entrega fica como Falhou no histórico, e é possível reenviá-la pelo ecrã (um ciclo novo, com o mesmo webhook-id).

#Desligamento automático

Se o destino ficar 72 horas sem nenhuma entrega com sucesso (com pelo menos 5 falhas no período), o webhook é desligado (Desligado por falha), as tentativas pendentes são canceladas e o proprietário e os administradores recebem um e-mail. Os eventos que acontecerem enquanto estiver desligado não são enviados depois.

Para voltar, use Religar no ecrã: a Memberfy envia um ping antes, e o webhook só volta se o destino responder 2xx.

#Endereço e rede

• Só https, na porta 443, num endereço público. Endereços internos, de rede privada ou de loopback são recusados.
• Sem redirecionamento e com 10 segundos de limite por tentativa. Da resposta, a Memberfy guarda só o início (1 KB), para o histórico.
• Se a sua firewall só aceita endereços conhecidos, marque Enviar de IPs fixos no webhook e autorize os IPs fixos da Memberfy.

#Limites

Cada entrega com sucesso de um evento conta em Webhooks entregues, no bloco Uso de Integrações & APIs. O ping não conta.

#Gerir por API

O ecrã usa a API de webhooks em https://developers.memberfy.net (/api/webhooks: listar, criar, editar o URL, a descrição, os eventos e os IPs fixos, enviar teste, rodar, desligar, religar, apagar, entregas, reenvio e histórico). Aceita só o token de início de sessão (Authorization: Bearer) com o X-CommunityId, de proprietário ou administrador; a chave de API não entra. A especificação está em developers.memberfy.net/docs.json. O catálogo de eventos é público: GET /api/integrations/events.

#Editar um webhook

PATCH /api/webhooks/{id} só com o que muda; um campo ausente fica como está.

curl -X PATCH https://developers.memberfy.net/api/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.memberfy.net/crm-v2", "events": ["member.*", "purchase.completed"], "fixedIps": true}'

• A configuração nova vale para os eventos que acontecerem depois. As entregas pendentes, em nova tentativa ou reenviadas depois seguem como foram criadas: o mesmo URL, o mesmo uso de IP fixo e o mesmo payload. A assinatura usa sempre o segredo atual.
• Trocar o url põe o failureCount a zero.
• Editar não religa: um webhook DISABLED ou DISABLED_FAILING continua desligado. Religar é POST /api/webhooks/{id}/enable, que envia o teste e só religa com resposta 2xx.
• Cada edição que muda algo torna-se uma linha updated no histórico, com o antes e o depois de cada campo em changes (URL mascarados). Uma edição sem mudanças não gera linha.
• Respostas: 200 com o webhook, 404, 422 (campo inválido, em errors[].param) e 429.

#Integrações prontas

As integrações prontas (Discord, Slack, Telegram, RD Station, HubSpot) usam a mesma API, em /api/apps: GET /api/apps (catálogo, com a instalação de cada app), PUT /api/apps/{slug}/installation (liga ou guarda a configuração e os eventos), POST …/installation/test, DELETE …/installation (desliga; com ?remove=true, remove e apaga a configuração e as entregas), POST /api/apps/telegram/chats (Encontrar meu grupo) e as entregas em …/installation/deliveries, com reenvio. As mesmas regras de acesso: token de início de sessão de proprietário ou administrador, nunca chave de API. Os campos secretos voltam mascarados; num PUT, um campo secreto ausente mantém o valor guardado.

#Relacionados

• Eventos de webhook
• IPs fixos
• Integrações & APIs
• Autenticação