Infoproductos y suscripciones
Kiwify en WhatsApp: recupera carrito, Pix y boleto sin escribir código
Kiwify envía un POST en JSON con cada evento de tu producto: boleto generado, Pix generado, carrito abandonado, compra aprobada, rechazada, reembolsada, chargeback y tres eventos de suscripción. ZapZap tiene un asistente llamado Recuperar vendas, en Fluxos, que genera la URL del webhook y un flujo listo para Kiwify. Pegas la URL en Kiwify, eliges el evento y el flujo envía el mensaje al teléfono del comprador.
Actualizado el
Por qué conectar
En Kiwify la venta se pierde en tres momentos: el cliente llena el checkout y desaparece, genera el Pix y no paga, o la renovación de la suscripción es rechazada. Cada uno tiene su propio evento, y cada evento puede convertirse en un mensaje en minutos, con el nombre y el producto ya completados. El flujo generado por ZapZap envía el primer mensaje al instante y, en los casos de carrito y de Pix o boleto, un segundo recordatorio después de una espera (30 minutos y 1 hora en los textos de partida, que puedes editar). Escribe solo a quien inició una compra contigo e incluye cómo dejar de recibir mensajes. ZapZap conecta números por un canal no oficial y gestionado, y el ritmo cuenta. Son R$15 por número activo al mes, prepago, con crédito de bienvenida al crear la cuenta, sujeto a la campaña vigente.
Paso a paso
- 1
Abre el asistente en Fluxos
En el panel de ZapZap, entra en Fluxos y haz clic en Recuperar vendas. Elige Kiwify, el objetivo (carrito abandonado, Pix o boleto sin pagar, o bienvenida tras la compra) y el número que enviará. El asistente crea el webhook, genera un flujo ya conectado y habilitado y muestra la URL, con el formato https://api.zapzapapi.com/api/webhooks/flow/{segredo}.
- 2
Registra la URL en Kiwify
En Kiwify, abre Apps, luego Webhooks y Criar webhook. Pega la URL de ZapZap, elige el producto (o todos) y marca los eventos del objetivo: carrinho_abandonado, pix_gerado y boleto_gerado, o compra_aprovada. Define un token largo y aleatorio: sin token, la firma se calcula con una clave vacía y no prueba nada. Usa Testar Webhook para enviar un evento de prueba.
- 3
Activa la validación de la firma
En el asistente de ZapZap, ingresa el token del webhook de Kiwify. Kiwify no envía el token: envía en la URL el parámetro signature, un HMAC-SHA1 en hexadecimal calculado sobre el cuerpo exacto de la solicitud, usando el token como clave. Con el token guardado, ZapZap verifica la firma de cada evento y responde 401 si no coincide. Sin token guardado, solo el secreto de la URL protege el webhook.
- 4
Comprueba que se encontró el teléfono
ZapZap guarda la última muestra recibida y detecta sola dónde están el teléfono, el nombre, el producto, el correo y el valor. Después de la primera prueba, abre el webhook en el editor y mira si apareció el campo teléfono. Si la respuesta de ZapZap llega con triggered: 0, el flujo no se disparó: el evento no traía teléfono, el número está fuera del formato de 10 a 13 dígitos o el número ya había recibido ese flujo en los últimos 10 minutos.
- 5
Edita los mensajes y haz una compra de prueba
Los textos de partida usan {nome} y {produto}. Reescríbelos con tu voz, quita lo que suene a presión y haz una compra real de valor bajo, o usa Testar Webhook apuntando a un número tuyo. Mira los logs de Kiwify en Ver logs: muestran el cuerpo enviado y la respuesta de ZapZap, y permiten reenviar.
Ejemplo
# Simula un evento de Kiwify en la URL del webhook de ZapZap (campos de ejemplo, usa un número tuyo).
# Si guardaste el token en el asistente, ZapZap responde 401 sin el signature correcto.
CORPO='{"order_id":"teste-001","order_status":"waiting_payment","webhook_event_type":"pix_created","Customer":{"full_name":"Maria Teste","mobile":"+5511999990001"}}'
curl -X POST 'https://api.zapzapapi.com/api/webhooks/flow/SEU_SEGREDO' \
-H 'Content-Type: application/json' \
-d "$CORPO"
# respuesta: {"ok":true,"triggered":1}
# Para validar la firma en TU servidor (camino sin el asistente), el cálculo de Kiwify es:
# signature = HMAC-SHA1(clave = token del webhook, mensaje = cuerpo crudo), en hexadecimal
printf '%s' "$CORPO" | openssl dgst -sha1 -hmac 'SEU_TOKEN_KIWIFY' -hexIlustrativo. Los campos y endpoints exactos están en la documentación.
Disparador de Kiwify y valor que llega en el payload
Kiwify advierte que el disparador que marcas y el valor de webhook_event_type en el cuerpo no siempre tienen el mismo nombre. Quien arma filtros por texto necesita la tabla de abajo, que sigue la documentación oficial.
| Disparador | webhook_event_type | order_status |
|---|---|---|
| boleto_gerado | billet_created | waiting_payment |
| pix_gerado | pix_created | waiting_payment |
| compra_aprovada | order_approved | paid |
| compra_recusada | order_rejected | refused |
| carrinho_abandonado | no se envía | no aplica (otro formato de payload) |
| subscription_late | subscription_late | estado del pedido más reciente de la suscripción |
Suscripción rechazada: el evento que salva ingresos recurrentes
Cuando la renovación de una suscripción es rechazada, Kiwify envía compra_recusada y subscription_late para el mismo pedido, y lo repite en cada nuevo intento de cobro que falle. Si se acaba el límite de intentos, la suscripción se cancela y llega subscription_canceled. Es la ventana adecuada para un aviso de ayuda ('tu tarjeta no pasó, ¿quieres cambiar la forma de pago?'). Si el cobro es rechazado antes del fin del período pagado, solo llega compra_recusada, y el acceso sigue vigente: no anuncies un corte de acceso que todavía no existe.
El asistente de ZapZap cubre carrito, Pix o boleto y poscompra. Para suscripción rechazada, el camino es el webhook genérico del editor de flujos, con el disparador de webhook y un filtro en el campo webhook_event_type, o un endpoint tuyo.
Idempotencia, reenvío y límites que debes conocer
- Confirmación: una respuesta 2xx confirma la entrega. Otro estado, una redirección o la falta de respuesta en 40 segundos cuenta como falla, y Kiwify reenvía varias veces, con intervalos de 1 a 10 minutos.
- Duplicidad: el mismo evento puede llegar más de una vez. La propia Kiwify recomienda la combinación order_id más webhook_event_type como clave. ZapZap ya ignora la repetición para el mismo flujo y teléfono durante 10 minutos.
- Replay: la firma de Kiwify no lleva fecha ni id de entrega, así que una solicitud capturada y reenviada sigue siendo válida. Quien necesite certeza del estado de una venta consulta GET /sales/{id} en la API de Kiwify.
- Cambio de token: no existe un período con los dos tokens válidos. Acepta ambos en tu servidor durante un día, o espera a que terminen los reenvíos pendientes.
- Límite de ZapZap: 120 solicitudes por minuto por webhook. Un lanzamiento grande puede superarlo; por encima del límite la respuesta es 429 y Kiwify lo intenta de nuevo.
Cuándo NO usar el asistente
Si necesitas armar un mensaje con datos que el asistente no extrae (enlace de recuperación, regla por rango de valor, consulta a tu base de datos), el asistente se queda corto y lo mejor es un endpoint tuyo o un flujo en n8n. Si el producto es de afiliado, el productor debe liberar los datos del comprador para que el teléfono llegue en el webhook. Y con una lista fría, que nunca inició una compra, no uses este camino: es prospección, y la prospección tiene otro riesgo y otra base legal.
Fuentes y fecha de verificación
Los disparadores, los valores de webhook_event_type, la firma HMAC-SHA1 en la query, el reenvío, la idempotencia y los eventos de suscripción se verificaron el 29 de octubre de 2026 en la documentación oficial de Kiwify (docs.kiwify.com.br), en las páginas Criar webhook, Receber e validar webhooks y Eventos de assinatura, y en el centro de ayuda de Kiwify. El bloque Customer del payload está resumido en la documentación; confirma los nombres exactos de los campos en Testar Webhook y Ver logs. El comportamiento de ZapZap proviene del código del producto en producción.
Preguntas frecuentes
¿Kiwify envía el token junto con el webhook?
No. El token no va en el encabezado, ni en la query ni en el cuerpo. Es la clave usada para firmar. Lo que Kiwify envía es el parámetro signature en la URL, un HMAC-SHA1 en hexadecimal del cuerpo exacto. Para validar, calcula el HMAC del cuerpo crudo con el token y compara en tiempo constante.
¿El evento de carrito abandonado tiene order_status?
No. El payload de carrito abandonado tiene otro formato, con datos del carrito y un estado propio, y no trae webhook_event_type ni order_status. Si filtras por esos campos, trata ese evento aparte.
El flujo no se disparó y la respuesta fue triggered: 0. ¿Qué reviso?
Tres causas comunes: el payload no tiene un teléfono de 10 a 13 dígitos, el teléfono salió del campo equivocado, o el mismo número ya recibió ese flujo en los últimos 10 minutos. Abre la muestra del webhook en el editor y mira qué campo detectó ZapZap como teléfono.
¿Necesito saber programar?
Para carrito, Pix, boleto y bienvenida, no: el asistente arma el flujo y la URL. Programar se vuelve necesario si quieres reglas propias, consultar tu base de datos o tratar una suscripción rechazada con lógica a medida.
¿Kiwify tiene entorno de pruebas?
No. La documentación dice que no hay sandbox ni modo de prueba para la API ni para los webhooks. El botón Testar Webhook envía datos ficticios con el mismo formato, y con él validas la recepción antes de una venta real.
¿El reembolso cancela la suscripción automáticamente?
Sí, según Kiwify. El reembolso o chargeback de un cobro de suscripción cancela la suscripción, y llegan dos webhooks: el de la compra y subscription_canceled. En el chargeback, customer_access no se pone en cero, así que retira el acceso a partir del evento chargeback.
¿Puedo enviar el mensaje de carrito a quien no terminó la compra?
Puedes cuando la persona dejó su teléfono en tu checkout, lo que crea una relación de compra iniciada. Sé breve, ofrece ayuda y permite dejar de recibir mensajes. ZapZap no elimina el riesgo de bloqueo de un canal no oficial, y la LGPD (la ley de protección de datos de Brasil) pide una base legal clara para el contacto.
Empieza ahora
Crea tu cuenta, conecta un número en minutos y prueba la API con calentamiento y anti-bloqueo. R$15 por número activo/mes, prepago, sin permanencia.