Webhooks

Apresentação

Um webhook é um endereço da internet (um URL) pertencente à sua associação: o do seu servidor, do seu CRM ou de uma ferramenta como o Make ou o Zapier. Assim que ocorre um evento na Donoor, a Donoor envia para esse endereço um pedido HTTPS POST que descreve o evento em formato JSON.

Cada mensagem é assinada com um segredo que só você conhece: o seu servidor pode assim verificar que vem mesmo da Donoor e que não foi alterada. Se o seu servidor não responder, a Donoor tenta novamente automaticamente durante cerca de 28 horas.

Início rápido

Conte cerca de quinze minutos para receber a sua primeira mensagem.

1. 1

   Prepare um endereço de receção

   Um endereço https acessível pela Internet, no seu servidor ou numa ferramenta como o Make ou o Zapier. Para experimentar sem instalar nada, basta um endereço gratuito do webhook.site.

2. 2

   Adicione-o ao seu painel

   Definições › Webhooks › Adicionar um endereço. Dê-lhe uma descrição e escolha os eventos a receber (todos, por predefinição).

3. 3

   Copie o segredo

   Começa por whsec_. Guarde-o na configuração do seu servidor, nunca numa página web ou num repositório de código público.

4. 4

   Verifique a assinatura e responda 200

   O seu servidor verifica o cabeçalho Donoor-Signature e responde com um código 2xx em menos de 10 segundos. O código pronto a copiar está mais abaixo, em Node.js, PHP e Python.

5. 5

   Envie uma mensagem de teste

   Botão Enviar um teste, ou Simular um evento para receber qualquer um dos 28 eventos com dados fictícios. Verifique depois o resultado no registo de envios.

Só são enviados os eventos que ocorrem depois de acrescentar o seu primeiro endereço: o histórico não é reenviado. As mensagens contêm o e-mail e o nome dos doadores: só o responsável e os administradores da associação podem gerir os webhooks, e o responsável é avisado por e-mail a cada endereço acrescentado ou alterado.

Lista dos eventos

Cada endereço recebe os eventos que assinalou. A coluna « Conteúdo » indica os objetos presentes em data, descritos na parte Objetos.

Uma encomenda paga desencadeia dois eventos: order.confirmed (a encomenda) e payment.succeeded (o dinheiro). Para medir as suas conversões, use apenas payment.succeeded; para gerir os seus inscritos, apenas order.confirmed. Subscreva cada endereço apenas aos eventos de que precisa.

As mensagens são normalmente enviadas menos de dois minutos após o facto: a Donoor aguarda que todas as informações estejam definitivas (montante transferido, taxas…) antes de enviar.

Estrutura de uma mensagem

Cada mensagem é um pedido POST cujo corpo JSON, codificado em UTF-8, tem sempre o mesmo envelope. Só o conteúdo de data muda conforme o tipo de evento. Os nomes dos campos estão em inglês, como na Stripe ou na HelloAsso.

Exemplos de mensagens

{
  "id": "evt_9mK2xQpL4vR8sT1w",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-10-17",
  "created": "2026-10-17T14:02:11.000Z",
  "livemode": true,
  "organization": {
    "id": 1234,
    "name": "Les Amis du Quartier"
  },
  "data": {
    "payment": {
      "id": 32631,
      "conversion_id": "32631",
      "order_id": null,
      "status": "succeeded",
      "amount": 50.6,
      "amount_cents": 5060,
      "net_amount": 49.3,
      "fees_covered_amount": 0.6,
      "provider_fee_amount": 1.3,
      "currency": "EUR",
      "refunded_amount": 0,
      "kind": "donation",
      "channel": "online",
      "form": null,
      "recurring": {
        "interval": "month",
        "sequence": "first",
        "subscription_id": 812
      },
      "payment_provider": "stripe",
      "payment_method": "card",
      "wallet": "apple_pay",
      "provider_reference": "pi_3UQZvoFXPodLa3BZ2HKqlaEw",
      "donor": {
        "email": "amina.k@exemple.fr",
        "name": "Amina K.",
        "anonymous": false
      },
      "created": "2026-10-17T14:01:02.000Z"
    },
    "attribution": {
      "parameters": {
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "ramadan-2027",
        "gclid": "Cj0KCQjw8eTFBhCXARIsAIkiuOz"
      },
      "landing_page": "https://www.mon-association.org/faire-un-don",
      "marketing_consent": true
    }
  }
}

Objetos

Os objetos que pode encontrar em data. Um campo sem valor fica com o valor null. As datas estão no formato ISO 8601, em UTC.

Todos os montantes são em euros, com duas casas decimais; os campos …_cents dão o mesmo montante em cêntimos. Os montantes são os da associação: o apoio facultativo que um doador deixa à Donoor nunca aparece aqui.

Cabeçalhos HTTP

Cada pedido inclui estes cabeçalhos. Os nomes dos cabeçalhos HTTP não diferenciam maiúsculas de minúsculas: o seu servidor pode recebê-los em minúsculas.

Verificar a assinatura

Qualquer pessoa pode enviar um pedido para o seu endereço: verifique por isso sempre a assinatura antes de confiar numa mensagem. O cabeçalho Donoor-Signature contém a data e hora de envio (t, em segundos) e uma ou duas assinaturas v1. Cada assinatura é um HMAC-SHA256, escrito em hexadecimal, do texto « data e hora + ponto + corpo bruto », calculado com o seu segredo.

Donoor-Signature: t=1792300000,v1=f0f590ea41b7f691921bb57c47f593d785d4e4d7d6c14f947848cb9d2d471bdf

1. 1

   Leia o corpo BRUTO do pedido, byte a byte, antes de qualquer descodificação JSON.

2. 2

   Recupere t e todos os valores v1 do cabeçalho Donoor-Signature.

3. 3

   Calcule o HMAC-SHA256 com o seu segredo (incluindo whsec_) sobre t + « . » + corpo, e compare o resultado com cada v1 através de uma comparação de tempo constante. Apenas uma deve corresponder.

4. 4

   Recuse a mensagem se t tiver mais de 5 minutos de diferença em relação ao seu relógio: uma mensagem intercetada não pode ser reproduzida mais tarde.

// Node.js (Express) — o corpo BRUTO é indispensável para a assinatura
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.DONOOR_WEBHOOK_SECRET; // whsec_…
const app = express();

app.post("/webhooks/donoor", express.raw({ type: "application/json" }), (req, res) => {
  const entete = req.get("Donoor-Signature") ?? "";
  const t = /t=(\d+)/.exec(entete)?.[1];
  const signatures = [...entete.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  const attendue = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");

  const valide = signatures.some((s) =>
    crypto.timingSafeEqual(Buffer.from(s, "hex"), Buffer.from(attendue, "hex")));
  const recent = t && Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!valide || !recent) return res.status(400).end();

  const evenement = JSON.parse(req.body.toString("utf8"));
  res.status(200).end(); // responder depressa, tratar depois
  traiter(evenement);    // processar o evento; ignorá-lo se o seu id já tiver sido visto
});

Exemplo de verificação

Para testar o seu código sem esperar por uma mensagem real: com estes valores, deve obter exatamente esta assinatura.

Erro mais frequente: assinar o JSON depois de o descodificar e recodificar. Um simples espaço ou a ordem das chaves altera a assinatura. Assine sempre o corpo exatamente como recebido.

Alterar o segredo

Se o seu segredo puder ter sido visto por outra pessoa, substitua-o: Definições › Webhooks › Segredo › Alterar o segredo.

Durante 24 horas, as mensagens são assinadas com o segredo antigo E com o novo: o cabeçalho contém então dois valores v1. Instale o novo segredo no seu servidor durante este prazo; depois, só o novo funciona.

O segredo é conservado encriptado pela Donoor. Só é apresentado aos responsáveis e administradores da associação.

Endereços aceites

• Apenas endereços https, com certificado válido.
• Porta 443 (a predefinida) ou 8443.
• O endereço tem de ser acessível pela Internet: endereços locais ou privados (localhost, rede interna) são recusados.
• Os redirecionamentos não são seguidos: uma resposta 3xx conta como falha. Indique o endereço final.
• A Donoor não envia a partir de uma lista fixa de endereços IP: não filtre por IP, verifique a assinatura.

Responder a uma mensagem

Responda com um código 2xx (200, 201, 204…) em menos de 10 segundos. O conteúdo da sua resposta não é lido, mas o seu início é apresentado no registo de envios para o ajudar a depurar.

Responda primeiro, trate depois: registe a mensagem, responda 200 e, em seguida, faça os processamentos longos (chamada ao Google Ads, envio de e-mail…) em segundo plano.

Lembretes e pausa

Quando um envio falha, a Donoor tenta novamente automaticamente: 8 tentativas no total, durante cerca de 28 horas.

1. 1.º envio
2. +1 min
3. +5 min
4. +30 min
5. +2 h
6. +5 h
7. +10 h
8. +10 h

• Após a 8.ª tentativa, a mensagem é abandonada e a associação é avisada por e-mail (no máximo um e-mail por endereço e por dia).
• Um endereço que não aceita nenhuma mensagem durante 3 dias é colocado em pausa automaticamente, com um e-mail. Reativa-se com um clique no painel.
• Qualquer mensagem do registo pode ser reenviada manualmente, durante 30 dias: botão Reenviar.

Duplicados e ordem

Um mesmo evento pode chegar mais do que uma vez: o seu servidor tratou a mensagem mas a resposta perdeu-se, ou alguém clicou em Reenviar. O evento mantém então o mesmo id: registe os id já tratados e ignore os que já conhece.

A ordem de chegada não é garantida: um reembolso pode, em caso de nova tentativa, chegar antes do pagamento de origem. Baseie-se no campo created e nos estados dos objetos, não na ordem de receção.

Para uma conversão publicitária, conversion_id basta: a Google e a Meta ignoram por si próprias uma conversão já recebida com o mesmo identificador.

Limites

Medir as suas campanhas

A mensagem payment.succeeded dá-lhe o montante, a moeda, o identificador de conversão e os parâmetros do anúncio de origem. O seu servidor transmite depois a conversão à plataforma publicitária: é fiável mesmo quando o navegador bloqueia os cookies ou os rastreadores.

Exemplo: um donativo transmitido ao GA4

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXX&api_secret=…

{
  "client_id": "donoor.32631",
  "events": [{
    "name": "purchase",
    "params": {
      "transaction_id": "32631",   // data.payment.conversion_id
      "value": 50.6,               // data.payment.amount
      "currency": "EUR",           // data.payment.currency
      "campaign": "ramadan-2027"   // data.attribution.parameters.utm_campaign
    }
  }]
}

Origem dos pagamentos

Acrescente os seus parâmetros de acompanhamento ao link dos seus anúncios, quer leve à sua página Donoor, quer à página do seu site que apresenta o widget da Donoor:

https://donoor.org/pay/mon-association?utm_source=google&utm_campaign=ramadan-2027&gclid=Cj0KCQjw…

• Todos os parâmetros da ligação são conservados até ao pagamento, mesmo que o doador abra a página de pagamento num novo separador.
• Chegam em data.attribution de payment.succeeded, e nos outros eventos do mesmo pagamento (reembolso, litígio, donativo mensal).
• Para uma renovação de donativo mensal, a origem é a do primeiro pagamento.
• Os parâmetros que se assemelham a um dado sensível (e-mail, palavra-passe, token, telefone, IBAN…) e os parâmetros técnicos da Donoor são descartados. No máximo 25 parâmetros, 300 caracteres por valor.
• attribution fica com o valor null quando o doador não chegou através de uma ligação com parâmetros.

Consentimento

attribution.marketing_consent indica se o doador aceitou os cookies publicitários na Donoor: true, false, ou null se não se souber.

Na Europa, a Google e a Meta exigem que respeite esta escolha (Google Consent Mode, RGPD). A sua associação continua responsável pela forma como utiliza estes dados: não envie o e-mail de um doador que recusou e lembre-se de mencionar este tratamento na sua política de privacidade.

Ensaios, simulações e registo

O botão Enviar um teste, em cada endereço, envia imediatamente um evento test.ping assinado como os outros. Serve para verificar se o seu servidor está acessível e se a sua assinatura está correta.

O botão Simular um evento, em cada endereço, envia um dos 28 eventos à escolha, no formato exato, com dados fictícios e livemode a false, apenas para esse endereço. Uma pré-visualização mostra a mensagem antes do envio. Não é efetuado nenhum pagamento, nem é enviado qualquer dado real.

Para desenvolver com calma, marque «Endereço de teste» na janela do endereço: nesse caso, só recebe simulações e mensagens de teste, nunca os eventos reais. Ligue-lhe o servidor de desenvolvimento da sua equipa e mantenha outro endereço para a produção.

O registo de envios mostra cada mensagem dos últimos 30 dias: evento, estado, número de tentativas, código HTTP e início da resposta do seu servidor, bem como o conteúdo exato enviado. Filtre por bem-sucedidos, com falha ou pendentes, e reenvie uma mensagem com um clique.

Ambiente de teste

O simulador basta para desenvolver os seus webhooks. Para testar também o percurso de pagamento completo (página de donativo, cartão de teste, recibo), a Donoor disponibiliza um ambiente de teste separado, em sandbox.donoor.org. As suas páginas não são referenciadas pelos motores de pesquisa.

1. Crie uma conta de associação de teste em dashboard-sandbox.donoor.org/register: não figura nenhum dado real.
2. Ligue a Stripe em Definições › Processo de recolha. Em modo de teste, a Stripe aceita dados fictícios (código SMS: 000000): não é necessária nenhuma conta bancária real.
3. A sua página de pagamento de teste fica imediatamente online, por exemplo sandbox.donoor.org/pay/votre-association, tal como as suas angariações, bilheteiras e lojas de teste.
4. Adicione o seu endereço de webhook em Definições › Webhooks, tal como em produção.
5. Faça um donativo nesta página com o cartão de teste 4242 4242 4242 4242 (data futura, qualquer código): recebe mensagens reais assinadas, com livemode a false. O segredo de teste é diferente do de produção.

Versões do formato

O campo api_version indica a versão do formato da mensagem. Só muda em caso de evolução incompatível (um campo renomeado ou eliminado, um significado alterado), anunciada com antecedência.

A Donoor pode, sem mudar de versão, acrescentar novos eventos e novos campos: o seu código deve ignorar o que não conhece.

Resolução de problemas