Webhooks de saída

Quando o Zapier não basta — você quer escrever seu próprio backend, rodar suas próprias automações, canalizar eventos para um data warehouse ou disparar serviços que o Zapier não suporta — os webhooks de saída lhe dão o fluxo bruto.

Um webhook é apenas um endpoint HTTPS que você hospeda. O GCM faz POST de JSON nele no momento em que algo acontece em sua organização. Mesma infraestrutura de entrega da integração com Zapier, mas apontando para sua URL em vez da do Zapier.

Quando usar webhooks vs Zapier

• Use Zapier quando o destino é um dos mais de 6.000 aplicativos que o Zapier já suporta, você não quer hospedar código e a precificação por tarefa do Zapier serve para você.
• Use webhooks quando você tem seu próprio backend, quer um único payload enviado para seu warehouse / fila / Lambda, ou quer custo zero por evento além da sua própria hospedagem.

Ambos compartilham a mesma política de tentativas, esquema de assinatura e log de entrega. A única diferença é qual URL recebe o POST.

Assinando eventos

Existem duas formas de criar uma assinatura de webhook:

Pela API

POST para /v1/subscriptions com sua chave de API:

curl -X POST https://api.geniuschurchmanager.com/v1/subscriptions \
  -H "Authorization: Bearer gcm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "member.created",
    "target_url": "https://your-server.example.com/gcm/webhook"
  }'

A resposta contém um subscription_id. Guarde-o — você precisará dele para desativar depois.

Pela interface

Em Integrations → Zapier, a aba Subscriptions mostra todas as assinaturas ativas, independentemente de se o Zapier ou um script feito à mão a criou. Você pode desativar mas não criar assinaturas pela interface — isso é intencional, já que URLs de destino devem ser gerenciadas por código.

Eventos disponíveis

Mesmo catálogo do Zapier:

Evento	Dispara
member.created	Qualquer nova linha de membro
member.updated	Mudanças de campos rastreados em um membro
donation.created	Linha de doação inserida
donation.refunded	Reembolso processado
attendance.recorded	Check-in ou presença salva
workflow.completed	Execução de workflow termina
form.submitted	Formulário público enviado
group.member_added	Membro adicionado a um grupo / ministério

Consulte a referência da API de webhooks para o formato exato dos campos de cada evento.

Verificação de assinatura

Cada POST carrega um cabeçalho X-GCM-Signature — um digest HMAC-SHA256 hex sobre o corpo bruto da requisição, com chave do segredo da sua assinatura.

import crypto from "node:crypto";

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

WARNING

Sempre verifique a assinatura antes de analisar o corpo ou fazer qualquer coisa com o payload. POSTs não assinados ou inválidos para o seu endpoint podem ser de qualquer um.

O segredo de assinatura é mostrado uma única vez quando a assinatura é criada. Guarde-o no seu gerenciador de segredos.

Contrato de resposta

Seu endpoint deve:

• Retornar HTTP 2xx em até 10 segundos — tratamos qualquer outra coisa como falha.
• Ser idempotente — podemos tentar novamente, e o mesmo ID de evento pode chegar duas vezes. O payload inclui um delivery_id que você pode usar para deduplicar.
• Fazer o trabalho de forma assíncrona se for lento. Persista o payload em uma fila e retorne 200 imediatamente; processe no seu ritmo.

Uma resposta 4xx é tratada como "esta requisição estava malformada e não terá sucesso na nova tentativa". Não tentamos de novo. Um 5xx é tratado como "o endpoint está tendo um dia ruim" e tentamos de novo com backoff.

Política de tentativas

Entregas falhadas são tentadas novamente com backoff exponencial:

Tentativa	Atraso após a falha anterior
1	inicial
2	1 minuto
3	5 minutos
4	25 minutos
5	2 horas

Após 5 falhas no total, a linha de entrega é marcada como failed e paramos. Após 10 falhas consecutivas no conjunto de entregas, a própria assinatura é desativada automaticamente — você verá um badge vermelho na interface e enviaremos um e-mail para o admin da organização.

Inspecionando entregas

A aba Recent deliveries em Integrations → Zapier mostra as últimas 50 tentativas de todas as assinaturas (Zapier e webhooks juntos).

Cada linha tem o status HTTP, contagem de tentativas, trecho da resposta e timestamp. Ao depurar "por que o evento X não disparou", este é o primeiro lugar para olhar.

Webhooks de entrada (a direção inversa)

Você também pode fazer com que seu sistema faça POST no GCM para disparar workflows. Configure um gatilho de webhook de entrada em qualquer workflow:

1. Construa um workflow com um nó disparador Webhook.
2. O GCM lhe dá uma URL com slug único (/functions/v1/receive-webhook/{slug}).
3. Configure seu sistema externo para POST nessa URL com X-Webhook-Signature (HMAC-SHA256 sobre o corpo usando o segredo que o GCM mostra).
4. Cada POST válido inicia uma nova execução de workflow com o payload disponível para etapas subsequentes.

Este é o caminho para receber eventos de sistemas que não têm integração com Zapier — seu software contábil, sua plataforma de transmissão ao vivo, um site de inscrição personalizado.

Limites de taxa

Limite	Padrão
Assinaturas ativas por organização	100
Taxa de entrega por assinatura	60 / minuto
Tamanho do payload	256 KB
Taxa de webhooks de entrada	60 / minuto / slug

Referências cruzadas

• Referência da API de webhooks — formatos exatos de payload dos eventos.
• Chaves de API — criar chaves para gerenciar assinaturas.
• Zapier — mesmo motor, destino sem código.
• Workflows — gatilhos de webhook de entrada em detalhes.