Webhooks de Stripe

Stripe envía eventos de donaciones, payouts y suscripciones a Ministrium vía webhook. Esta página explica cómo se procesan y cómo verificar la firma si decide consumir webhooks de Ministrium hacia su backend.

Webhooks Stripe → Ministrium (gestionados)

Cuando conecta Stripe (vía Stripe Connect), Ministrium automáticamente crea un endpoint en su cuenta Stripe:

https://api.ministrium.com/v1/webhooks/stripe/<tenant>

Eventos suscritos: ver Stripe Connect → Webhooks.

Estos webhooks son internos — usted no necesita configurarlos. Sirven para que Ministrium reaccione a cambios de Stripe en tiempo real.

Webhooks Ministrium → su backend (salientes)

Si quiere que Ministrium notifique a su backend cuando algo pasa (donación, miembro nuevo, etc.):

1. Configuración → API → Webhooks → Nuevo.
2. URL del endpoint (HTTPS obligatorio).
3. Eventos a los que se suscribe (puede elegir varios).
4. Guarda → Ministrium genera un signing secret whsec_....

Eventos disponibles

member.created           member.updated           member.deleted
prospect.created         prospect.converted
attendance.recorded
donation.created         donation.refunded        donation.disputed
recurring.created        recurring.updated        recurring.canceled  recurring.charge_failed
event.created            event.registration       event.canceled
group.created            group.multiplied         group.closed
prayer_request.created   prayer_request.answered
campus.created
tag.added                tag.removed
device.registered

Estructura del payload

{
  "id": "evt_xyz789",
  "type": "donation.created",
  "created": 1714165800,
  "tenant": "la-roca",
  "api_version": "2026-01-01",
  "data": {
    "object": {
      "id": "don_abc123",
      "amount": 50000,
      "currency": "MXN",
      "fund": { "id": "fnd_diezmos", "name": "Diezmos" },
      "donor": { "id": "mem_456", "first_name": "Juan" },
      "campus": { "id": "cmp_centro", "name": "Centro" },
      "created_at": "2026-04-26T14:30:00Z"
    }
  }
}

tenant siempre presente para identificar a qué iglesia pertenece (útil si usted opera para varias).

Verificación de firma

Ministrium firma cada webhook con HMAC-SHA256:

Headers:
Ministrium-Signature: t=1714165800,v1=abcd1234...

Verificación en Node.js:

import crypto from 'crypto';
 
function verify(payload, header, secret) {
  const [tPart, vPart] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const signature = vPart.split('=')[1];
 
  // Tolerancia de 5 minutos para evitar replay
  if (Math.abs(Date.now()/1000 - timestamp) > 300) return false;
 
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

> Importante: use el raw body (no el JSON parseado) para calcular la firma.

Reintentos y idempotencia

Si su endpoint no responde 2xx en < 3 s, Ministrium reintenta con backoff (ver Rate limits).

Cada evento tiene un id único. Su backend debe ser idempotente: guardar los IDs procesados y descartar duplicados.

if (await db.events.exists({ id: payload.id })) return res.status(200).end();
await db.events.insert({ id: payload.id, ... });

Replay y backfill

En Configuración → API → Webhooks → [Endpoint] puede:

• Reenviar un evento puntual (útil si su backend tuvo bug).
• Backfill de un rango de fechas (todos los eventos de tipo X entre fecha A y B).

Buenas prácticas

1. Verifique siempre la firma. Ataques de replay son reales.
2. Responda 200 rápido y procese asíncrono.
3. Guarde el evento crudo antes de procesarlo (debugging).
4. Monitoree fallos: si su endpoint cae, los webhooks se desactivan tras 5 reintentos.
5. Tenga un endpoint de health-check (GET /webhooks/ping) que Ministrium puede llamar para validar antes de enviar.