Stripe
Los clientes, suscripciones, facturas, checkout y disputas de Stripe se convierten en contactos y eventos que disparan automatizaciones.
Con la integración de Stripe, cada cliente se convierte en contacto y cada cobro, suscripción o disputa se convierte en un evento que puede iniciar una automatización: un correo electrónico cuando falla el pago, un recordatorio cuando la prueba gratuita está por terminar, una encuesta cuando alguien cancela.
#Crea la conexión
En el panel, abre Integraciones › Tu app y haz clic en Conectar en la tarjeta de Stripe. La conexión tiene tu URL, que pegas en el proveedor, y muestra el paso a paso en la propia pantalla.
https://api.postal.so/integrations/crm/01a1c2d3-e4f5-7a6b-8c9d-0e1f2a3b4c5d/webhookEn Stripe, abre Desarrolladores › Webhooks, haz clic en Añadir destino, pega la URL y elige los eventos de la tabla de abajo. Después, abre el destino, revela el Secreto de firma (whsec_…) y pégalo en la conexión. El secreto queda cifrado y no vuelve a aparecer.
Cómo comprueba Postal
Cada solicitud necesita el encabezado Stripe-Signature válido para el secreto y con un máximo de 5 minutos. Sin él, la respuesta es 401 y no cambia nada.
Las integraciones de app cuentan en el límite del plan (app_integrations). Fuera del plan, las tarjetas aparecen bloqueadas con el botón Mejorar plan.
#Eventos
Todo evento lleva también stripe_event_id, customer_id y livemode. Los valores de dinero vienen en la unidad de la moneda (49.9 para R$ 49,90), con la moneda en mayúsculas (BRL).
| Evento de Stripe | Evento en Postal | Cuándo | Propiedades |
|---|---|---|---|
checkout.session.completed | stripe.checkout.session.completed | Checkout completado | checkout_session_id, amount, currency, mode, payment_status, subscription_id |
checkout.session.async_payment_succeeded | stripe.checkout.session.async_payment_succeeded | Pago asíncrono (boleto, Pix) aprobado | las del checkout |
checkout.session.async_payment_failed | stripe.checkout.session.async_payment_failed | Pago asíncrono rechazado o vencido | las del checkout |
customer.created | stripe.customer.created | Cliente creado | customer_id, name, phone |
customer.updated | stripe.customer.updated | Cliente actualizado | las del cliente |
customer.deleted | stripe.customer.deleted | Cliente eliminado (eliminación, véase abajo) | las del cliente |
customer.subscription.created | stripe.customer.subscription.created | Suscripción creada | subscription_id, status, plan, price_id, product_id, amount, currency, interval, trial_end, current_period_end |
customer.subscription.updated | stripe.customer.subscription.updated | Suscripción modificada (plan, estado, cancelación programada) | las de la suscripción, más cancel_at_period_end |
customer.subscription.paused | stripe.customer.subscription.paused | Suscripción pausada | las de la suscripción |
customer.subscription.resumed | stripe.customer.subscription.resumed | Suscripción reanudada | las de la suscripción |
customer.subscription.trial_will_end | stripe.customer.subscription.trial_will_end | La prueba gratuita termina en 3 días | las de la suscripción |
customer.subscription.deleted | stripe.customer.subscription.deleted | Suscripción cancelada | las de la suscripción, más cancellation_reason |
invoice.paid | stripe.invoice.paid | Factura pagada | invoice_id, invoice_number, amount, currency, status, billing_reason, plan, hosted_invoice_url, invoice_pdf |
invoice.payment_failed | stripe.invoice.payment_failed | Fallo en el pago de la factura | las de la factura, más attempt_count y next_payment_attempt |
invoice.upcoming | stripe.invoice.upcoming | Próxima factura (días antes del cobro) | las de la factura, más amount_due y period_end |
charge.dispute.created | stripe.charge.dispute.created | Disputa abierta | dispute_id, charge_id, amount, currency, reason, status |
charge.dispute.closed | stripe.charge.dispute.closed | Disputa cerrada | las de la disputa |
Los demás eventos de Stripe se aceptan y se ignoran.
#Qué contacto
El contacto es el cliente de Stripe, identificado por el correo electrónico que llega en el propio evento (el del cliente, customer_email de la factura o customer_details.email del checkout). Postal no llama a la API de Stripe: cuando el evento trae solo el ID del cliente (como las suscripciones), vale el contacto que un evento anterior ya vinculó a ese ID. Sin correo electrónico y sin contacto vinculado, el evento se omite y aparece como “ignorado” en el registro.
El nombre del cliente pasa a ser el nombre y el apellido del contacto, y metadata.user_id (o userId, external_id) pasa a ser el external_id: guarda en él el ID del usuario en tu app al crear el cliente en Stripe.
await stripe.customers.create({
email: '[email protected]',
name: 'Fulano de Tal',
metadata: { user_id: user.id },
})Para customer.deleted, la conexión define qué hacer con el contacto: solo registrar el evento (predeterminado), dar de baja al contacto (sigue en la audiencia, pero sin recibir marketing) o eliminar el contacto (sin evento, ya que el contacto desaparece). Una eliminación nunca crea un contacto que Postal no tenía.
#Configuración de la conexión
- Eventos: solo los marcados se convierten en contacto y evento; los demás se ignoran (la respuesta sigue siendo
202). - Sincronizar el nombre: actualiza el nombre y el apellido del contacto con lo que llegue del proveedor.
- Añadir al segmento y Suscribir al tema: un segmento estático y un tema para cada contacto que llega.
- Cuando el usuario se elimine en la app: solo registrar, dar de baja o eliminar el contacto.
Todo lo que la conexión cambia en el contacto lleva el origen crm:<id da conexão> (last_change_source), y cada entrega aparece en el registro de la conexión, con el resultado de cada persona. Una entrega repetida por el proveedor (mismo ID) no se procesa dos veces.
#Dispara automatizaciones
Cada evento queda en el contacto con el nombre stripe.invoice.payment_failed y las propiedades de la tabla anterior. En la pantalla de la conexión, el botón Crear automatización junto a cada evento abre una automatización nueva con el disparador Evento recibido ya completado. Con los endpoints de automatizaciones, el disparador es {"type": "event", "event": "stripe.invoice.payment_failed"}.
Ejemplo: cuando falla el cobro, envía un correo electrónico con el botón a la factura ({{event.hosted_invoice_url}}) y, si pasados 3 días no hay stripe.invoice.paid, un segundo aviso. En los correos, las propiedades del evento entran como {{event.amount}} en los pasos o como variables de la plantilla ({{{amount}}}).
#Probar
Con la CLI de Stripe, lanza eventos de prueba a tu destino:
stripe trigger customer.created
stripe trigger invoice.payment_failedEl contacto aparece en Audiencia y el evento en Eventos. En Stripe, cada entrega muestra la respuesta de Postal (202 aceptado, 401 firma no válida, 409 conexión pausada).
Próximos pasos
La conexión con un clic (app de Stripe, sin copiar el secreto) está en los planes. Por ahora, el destino se crea a mano en Stripe.