Webhooks salientes

Cuando Zapier no es suficiente — quieres escribir tu propio backend, ejecutar tus propias automatizaciones, canalizar eventos a un data warehouse o disparar servicios que Zapier no admite — los webhooks salientes te dan la manguera cruda.

Un webhook es solo un endpoint HTTPS que tú alojas. GCM hace POST de JSON a él en el momento en que algo ocurre en tu organización. Misma infraestructura de entrega que la integración con Zapier, pero apuntando a tu URL en lugar de la de Zapier.

Cuándo usar webhooks vs Zapier

• Usa Zapier cuando el destino es una de las más de 6,000 aplicaciones que Zapier ya admite, no quieres alojar código y te parecen bien los precios por tarea de Zapier.
• Usa webhooks cuando tienes tu propio backend, quieres una sola carga útil enviada a tu warehouse / cola / Lambda, o quieres cero costo por evento más allá de tu propio hosting.

Ambos comparten la misma política de reintentos, esquema de firma y registro de entrega. La única diferencia es qué URL recibe el POST.

Suscribirse a eventos

Hay dos maneras de crear una suscripción a webhook:

A través de la API

Haz POST a /v1/subscriptions con tu clave 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"
  }'

La respuesta contiene un subscription_id. Guárdalo — lo necesitarás para desactivarlo luego.

A través de la interfaz

En Integraciones → Zapier, la pestaña Suscripciones muestra cada suscripción activa, sin importar si fue creada por Zapier o por un script propio. Puedes desactivar pero no crear suscripciones desde la interfaz — esto es intencional, ya que las URLs de destino deben gestionarse por código.

Eventos disponibles

El mismo catálogo que Zapier:

Evento	Se dispara cuando
member.created	Cualquier nueva fila de miembro
member.updated	Cambios en campos rastreados de un miembro
donation.created	Se inserta una fila de donación
donation.refunded	Se procesa un reembolso
attendance.recorded	Se guarda un check-in o asistencia
workflow.completed	Termina la ejecución de un flujo
form.submitted	Se envía un formulario público
group.member_added	Se agrega un miembro a un grupo / ministerio

Consulta la referencia de la API de webhooks para la forma exacta de los campos de cada evento.

Verificación de firma

Cada POST lleva una cabecera X-GCM-Signature — un digest hexadecimal HMAC-SHA256 sobre el cuerpo crudo de la solicitud, con clave del secreto de tu suscripción.

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

Verifica siempre la firma antes de analizar el cuerpo o hacer cualquier cosa con la carga útil. Los POSTs sin firma o con firma inválida en tu endpoint podrían ser de cualquiera.

El secreto de firma se muestra una sola vez al crear la suscripción. Guárdalo en tu gestor de secretos.

Contrato de respuesta

Tu endpoint debe:

• Devolver HTTP 2xx en menos de 10 segundos — tratamos cualquier otra cosa como un fallo.
• Ser idempotente — podemos reintentar, y el mismo ID de evento puede llegar dos veces. La carga útil incluye un delivery_id que puedes usar para deduplicar.
• Hacer el trabajo de forma asíncrona si es lento. Persiste la carga útil en una cola y devuelve 200 de inmediato; procesa cuando puedas.

Una respuesta 4xx se trata como "esta solicitud estaba mal formada y no tendrá éxito al reintentar". No reintentamos. Una 5xx se trata como "el endpoint está pasando un mal día" y reintentamos con backoff.

Política de reintentos

Las entregas fallidas se reintentan con backoff exponencial:

Intento	Retraso tras el fallo anterior
1	inicial
2	1 minuto
3	5 minutos
4	25 minutos
5	2 horas

Después de 5 fallos totales, la fila de entrega se marca como failed y nos detenemos. Después de 10 fallos consecutivos entre entregas, la suscripción misma se desactiva automáticamente — verás una insignia roja en la interfaz y enviaremos un correo al admin de la organización.

Inspeccionar entregas

La pestaña Entregas recientes en Integraciones → Zapier muestra los últimos 50 intentos entre todas las suscripciones (Zapier y webhooks por igual).

Cada fila tiene el estado HTTP, el contador de reintentos, un extracto de la respuesta y la marca de tiempo. Al investigar "por qué no se disparó el evento X", este es el primer sitio donde mirar.

Webhooks entrantes (la dirección inversa)

También puedes hacer que tu sistema haga POST hacia GCM para disparar flujos. Configura un disparador de webhook entrante en cualquier flujo:

1. Construye un flujo con un nodo disparador Webhook.
2. GCM te da una URL con slug único (/functions/v1/receive-webhook/{slug}).
3. Configura tu sistema externo para hacer POST a esa URL con X-Webhook-Signature (HMAC-SHA256 sobre el cuerpo usando el secreto que GCM te muestra).
4. Cada POST válido inicia una nueva ejecución de flujo con la carga útil disponible para los pasos siguientes.

Este es el camino para recibir eventos de sistemas que no tienen integración con Zapier — tu software contable, tu plataforma de transmisión en vivo, un sitio de registro personalizado.

Límites de tasa

Límite	Predeterminado
Suscripciones activas por organización	100
Tasa de entrega por suscripción	60 / minuto
Tamaño de carga útil	256 KB
Tasa de webhooks entrantes	60 / minuto / slug

Referencias cruzadas

• Referencia de webhooks de la API — formas exactas de carga útil para cada evento.
• Claves de API — crear claves para gestionar suscripciones.
• Zapier — mismo motor, destino sin código.
• Flujos de trabajo — disparadores de webhook entrante en detalle.