Webhooks

Entrada — os que recebemos

Genius Checkout

URL: POST /functions/v1/gc-webhook

O GC publica eventos para cada mudança de estado de assinatura (created, charged, paused, cancelled, payment_failed). Cada publicação carrega:

• X-GC-Signature — HMAC-SHA256 sobre o corpo bruto usando o webhook_secret da sua organização.
• Idempotency-Key — o GC reenvia respostas 5xx não assinadas por cerca de 24 horas, então proteja-se contra duplicatas do seu lado.

Verificamos a assinatura, procuramos a linha correspondente em recurring_donations por gateway_subscription_id e atualizamos seu estado. O payload completo é registrado em donation_payment_webhook_log para que você possa reproduzi-lo se uma escrita falhar.

Respostas de entrada do WAHA / WhatsApp

URL: POST /functions/v1/wacrm-webhook

O WAHA publica JSON para cada mensagem de WhatsApp recebida + confirmação de entrega. Normalizamos o número de telefone (apenas dígitos, sem +), o comparamos com members.primary_phone e adicionamos a mensagem ao tópico de conversa existente (ou criamos um novo).

Reembolsos + notificações do PowerTranz

URL: POST /functions/v1/powertranz-webhook

Usado para confirmações assíncronas de reembolso + notificações de pagamento recorrente. Mesmo padrão HMAC que o GC.

Saída — os que você pode configurar

Webhooks por evento

Vá em Configurações → Integrações → Webhooks e adicione uma URL. Escolha entre:

Evento	Dispara quando
member.created	Um novo membro é adicionado (manualmente, em massa ou via formulário de visitante)
member.lost	Um membro é marcado como perdido
donation.recorded	Uma linha de doação é inserida (manual ou online)
attendance.marked	Uma linha de presença é inserida
workflow.completed	Uma execução de workflow termina

Cada publicação inclui:

• X-GCM-Signature — HMAC-SHA256 do corpo usando um segredo que você define.
• Um corpo JSON com a linha afetada + delta.

Zapier

Oferecemos uma integração com o Zapier (procure por "Genius Church Manager" no Zapier). Use-a para automações low-code. Por baixo dos panos é o mesmo endpoint de webhook de saída.

Verificando assinaturas

Pseudocódigo (o mesmo algoritmo funciona em Node, Python, PHP, Go):

expected = HMAC_SHA256(secret, raw_body).hex()
got = request_header('X-GCM-Signature')
if not constant_time_compare(expected, got):
    return 401

WARNING

Não use == — apenas comparação em tempo constante. Stripe e Slack publicam guias mais detalhados, ambos se aplicam aqui.

Novas tentativas

Reenviamos publicações que falharam (status ≠ 2xx, ou sem resposta em 10s) com backoff exponencial por até 24 horas, então marcamos a entrega como permanently_failed. Verifique o histórico de entregas em Configurações → Integrações → Logs de Webhook.