Recibir eventos de tu tienda con webhooks

En este artículo te mostraremos cómo configurar webhooks para que tu tienda avise a tus propios sistemas (un ERP, un CRM, un sistema de facturación) cada vez que se registra una venta.

Cuando ocurre un evento al que te suscribiste, Publica.la envía una solicitud POST con los datos en formato JSON y firmada a la URL que indiques. Los webhooks están disponibles para todas las tiendas y reemplazan al webhook de venta anterior, con varias ventajas: puedes tener hasta 10 destinos, cada uno con su propia clave y sus propios eventos, y cada aviso incluye una clave para evitar procesarlo dos veces.

Antes de empezar​

• Solo los administradores de la tienda pueden gestionar los webhooks. Los administradores de plan no tienen acceso a esta sección.
• Tu tienda puede tener hasta 10 endpoints. Un endpoint es cada URL de tu sistema que recibe los avisos.
• La URL debe ser pública: usa http o https, el puerto 80 o 443 y una dirección que no sea interna. No seguimos redirecciones. Te recomendamos https para que los datos viajen cifrados.

Eventos disponibles​

Una compra nueva genera los dos eventos, y pueden llegar en cualquier orden. Para saber si un cobro es una renovación, revisa el campo charge.recurring_cycle del evento Cobro pagado: 1 es el primer cobro de una suscripción, un número mayor que 1 es una renovación y null es una compra de pago único.

Crear un endpoint​

1. Ingresa al Panel de Control y ve a Ajustes > Webhooks.

2. Haz clic en Agregar endpoint y completa los datos:

• Nombre: opcional. Te ayuda a distinguir un endpoint de otro.
• URL: la dirección de tu sistema que recibirá un POST por cada evento.
• Eventos: marca Orden pagada, Cobro pagado o ambos.
• Activo: déjalo activado para empezar a recibir los avisos. Si lo desactivas, el endpoint queda pausado.

3. Haz clic en Guardar. Verás el aviso "Endpoint creado" y un recuadro con la clave de firma del endpoint, un código de 64 caracteres que usarás para comprobar que los avisos vienen de Publica.la.

Enviar una prueba​

Para comprobar que tu sistema recibe los avisos, abre el menú del endpoint y haz clic en Enviar prueba. Enviamos un ejemplo del primer evento al que está suscrito el endpoint, con los encabezados y la firma reales pero con datos ficticios. Verás el aviso "Evento de prueba en cola" y, en unos instantes, el intento aparece en Entregas recientes (haz clic en Actualizar).

• Puedes enviar hasta 5 pruebas por minuto por endpoint. Si superas el límite, el panel te indica cuántos segundos esperar.
• La prueba se intenta una sola vez, se envía aunque el endpoint esté pausado o deshabilitado y no cuenta para la desactivación automática.
• Su clave de idempotencia empieza con test:, así puedes distinguirla de un aviso real.

Revisar las entregas recientes​

Debajo de la lista de endpoints, la sección Entregas recientes muestra los últimos 50 intentos de entrega y se conservan por 30 días. Cada intento muestra la fecha, el endpoint, el evento, el estado, el número de intento, el código de respuesta y la duración. Los estados son:

• Entregado: tu sistema respondió con un código 2xx.
• Fallido: el intento falló y se volverá a intentar mientras queden intentos.
• Omitido: no se envió porque el endpoint estaba pausado, deshabilitado o eliminado, o porque el evento ya había llegado a ese endpoint.

Administrar tus endpoints​

Desde el menú de cada endpoint puedes:

• Editar: cambiar el nombre, la URL o los eventos. Si cambias la URL, se reinicia el conteo de fallos y se vuelve a habilitar un endpoint deshabilitado.
• Pausar / Reanudar: dejar de enviar avisos y volver a enviarlos. Los eventos que ocurran mientras el endpoint está en pausa se descartan, no se guardan para enviarlos después.
• Rotar clave de firma: generar una clave nueva. La anterior deja de funcionar de inmediato, así que actualiza tu sistema antes o justo después.
• Volver a habilitar: en un endpoint deshabilitado, el panel muestra el último error y te permite habilitarlo de nuevo.
• Eliminar: borrar el endpoint. Te pedimos confirmación porque es inmediato y no se puede deshacer: el endpoint deja de recibir eventos y sus entregas dejan de mostrarse.

Qué recibe tu sistema​

Cada aviso llega como un POST con un cuerpo JSON y estos encabezados:

Para tu equipo técnico, algunas recomendaciones:

• Verifica la firma con la clave de firma antes de procesar el aviso, y rechaza los que tengan una marca de tiempo con más de 5 minutos de diferencia.
• Responde con un código 2xx en menos de 10 segundos. Cualquier otra respuesta se considera un fallo.
• Evita duplicados con X-Pla-Idempotency-Key: puedes recibir el mismo aviso más de una vez y el orden entre eventos no está garantizado.

El detalle de la firma, los campos de cada evento y un ejemplo de verificación están en la documentación técnica de webhooks.

Reintentos y desactivación automática​

Si tu sistema no responde con un código 2xx, reintentamos la entrega hasta 12 veces durante unas 70 horas, con esperas cada vez más largas (1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas y luego 12 horas).

Un endpoint se deshabilita automáticamente cuando sus últimas 5 entregas agotaron todos los intentos y no tuvo ninguna entrega exitosa en las últimas 72 horas. Mientras está deshabilitado no recibe nada: los eventos nuevos se descartan y no enviamos ningún aviso por correo. El panel lo muestra como Deshabilitado hasta que lo habilites de nuevo.

Migrar desde el webhook de venta anterior​

El webhook de venta anterior (el que se configura en Ajustes > Integraciones) sigue funcionando por ahora, pero está en desuso. Puedes tener ambos activos al mismo tiempo: crea tus endpoints nuevos, comprueba que tu sistema los procesa bien y recién entonces desactiva el anterior. Ten en cuenta estas diferencias:

• El webhook anterior enviaba una solicitud por cada producto pagado. Ahora recibes un solo evento Cobro pagado por cobro, con todos los pagos en data.payments.
• La firma ya no es un token JWT: ahora es una firma HMAC-SHA256 del cuerpo, en el encabezado X-Pla-Signature.
• Las renovaciones, los cobros de envío y los canjes de Publica One llegan como eventos Cobro pagado.

Tienes la guía completa en la documentación técnica. Si todavía usas el webhook anterior, consulta Configurar Webhooks.

Preguntas frecuentes​

¿Puedo enviar cada evento a un sistema distinto? Sí. Crea un endpoint por sistema (hasta 10) y marca en cada uno solo los eventos que necesita. Cada endpoint tiene su propia clave de firma.

Perdí la clave de firma. ¿Puedo verla de nuevo? No, solo se muestra al crear el endpoint y al rotarla. Usa Rotar clave de firma para generar una nueva y actualízala en tu sistema.

Mi endpoint dejó de recibir avisos. ¿Qué reviso? Abre Ajustes > Webhooks y revisa si el endpoint figura como pausado o Deshabilitado. Si es así, corrige el problema en tu sistema, usa Enviar prueba y vuelve a habilitarlo. Las Entregas recientes muestran el último error.

¿Cómo pruebo sin programar nada? Puedes usar un servicio de recepción de solicitudes como webhook.site, que te da una URL pública temporal. Ten en cuenta que cualquiera con esa URL puede ver los datos que lleguen, incluidos datos reales de ventas: elimina el endpoint al terminar.

Al guardar, la URL es rechazada. ¿Por qué? La URL debe ser pública, empezar con http:// o https:// y usar el puerto 80 o 443. Las direcciones privadas o locales no se aceptan.

La prueba falla con un código 3xx. ¿Qué hago? Tu sistema está redirigiendo. No seguimos redirecciones, así que configura la URL final exacta.

¿Recibiré los eventos que ocurrieron mientras el endpoint estaba pausado o deshabilitado? No. Esos eventos se descartan y no se reenvían.

Recursos útiles​

• Documentación técnica de webhooks
• Configurar Webhooks (webhook de venta anterior)

Esperamos que este tutorial te haya resultado sencillo. Si tienes consultas escríbenos a [email protected].