Un webhook de WooCommerce es un mensaje que tu tienda envía a otro servicio cuando ocurre algo, como que se crea o se actualiza un pedido. Lo configuras una sola vez en WooCommerce, Ajustes, Avanzado, Webhooks: eliges el evento (el tema), la dirección a la que va (la URL de entrega) y un secreto con el que se firma cada mensaje. A partir de ahí, WooCommerce entrega el pedido a esa dirección cada vez que se dispara el evento. Casi todos los problemas vienen de cuatro sitios: el tema equivocado, un secreto distinto en cada lado, un webhook sin un usuario con permiso para leer pedidos y entregas en pausa o con retraso.
Esta guía explica cada campo con palabras sencillas y luego repasa esos errores.
Qué es un webhook, en términos de tienda
Piénsalo como un email automático entre dos sistemas. En lugar de que una persona revise tus pedidos y los copie en otro sitio, WooCommerce envía cada pedido a un servicio en el momento en que cambia. Ese servicio puede ser una herramienta de contabilidad, un socio logístico o un widget de notificaciones de ventas.
Dos cosas hacen que esto sea mejor que copiar datos a mano o con una exportación nocturna:
- Es inmediato. El servicio que lo recibe se entera de un pedido en cuestión de momentos.
- Se puede comprobar. Con un secreto, el receptor puede demostrar que el mensaje vino de tu tienda y no se alteró por el camino.
Los campos de la pantalla del webhook
| Campo |
Qué significa |
Qué poner |
| Nombre |
Una etiqueta para ti |
Algo que diga adónde va, como "Pedidos a Provedly" |
| Estado |
Activo, En pausa o Desactivado |
Activo, cuando estés listo |
| Tema |
Qué evento dispara una entrega |
Normalmente un tema de pedido, ver abajo |
| URL de entrega |
Adónde envía WooCommerce el mensaje |
La dirección que te da el servicio receptor, empezando por https |
| Secreto |
Un valor compartido con el que se firma cada mensaje |
Un valor largo que también pegas en el servicio receptor |
| Versión de la API |
El formato del mensaje |
La versión actual de la WP REST API, salvo que el servicio diga otra cosa |
Hay un ajuste que no ves como campo pero que importa mucho: cada webhook pertenece a un usuario de WordPress. WooCommerce construye cada entrega leyendo el pedido a través de su propia API REST como ese usuario. Si el usuario no puede leer pedidos, la entrega contiene un error en lugar del pedido.
order.created u order.updated
Estos dos temas son donde fallan la mayoría de las configuraciones.
- order.created se dispara una vez, cuando el pedido se guarda por primera vez. Con muchos métodos de pago eso ocurre antes de que el cliente haya pagado, así que el pedido puede seguir en Pendiente de pago.
- order.updated se dispara cada vez que el pedido cambia: cuando se completa el pago y el estado pasa a Procesando, cuando lo marcas como Completado, cuando añades una nota.
Si quieres actuar solo sobre pedidos pagados, order.created por sí solo puede perderse el momento del pago y puede entregar pedidos que nunca se pagan. order.updated ve el pago, pero también envía el mismo pedido varias veces. La solución habitual es escuchar order.updated y que el servicio receptor haga dos cosas: ignorar los pedidos cuyo estado no sea pagado y recordar qué ids de pedido ya ha procesado.
Eso es exactamente lo que hace Provedly con WooCommerce. Registra un pedido solo cuando su estado es Procesando o Completado, y registra cada id de pedido una sola vez, lleguen las actualizaciones que lleguen. También acepta entregas de order.created, con las mismas reglas.
El secreto y la firma
Cuando un webhook tiene un secreto, WooCommerce pasa el cuerpo del mensaje y el secreto por una función hash (HMAC-SHA256) y envía el resultado en una cabecera llamada X-WC-Webhook-Signature. El servicio receptor hace el mismo cálculo con su copia del secreto. Si los dos resultados coinciden, el mensaje vino de alguien que conoce el secreto y no se modificó por el camino. Si no coinciden, el servicio debería descartar el mensaje.
Puntos prácticos:
- El secreto debe ser idéntico en ambos lados, incluidas las mayúsculas y sin espacios de más.
- Elige un valor largo y aleatorio, y no lo dejes ver en capturas de pantalla ni en tickets de soporte.
- Cambiarlo en un lado rompe las entregas hasta que lo cambies en el otro.
La firma es lo que permite que una notificación de ventas diga con honestidad "Compra verificada". Sin ella, cualquiera que conociera la URL de entrega podría enviar un pedido inventado. Nuestra explicación sobre los secretos de firma de webhooks compara cómo lo hacen Stripe, Shopify y WooCommerce.
Errores comunes y cómo arreglarlos
| Lo que ves |
Causa |
Arreglo |
| El servicio receptor recibe un error de la API REST en lugar del pedido, a menudo sobre permisos |
El usuario del webhook no puede leer pedidos, o el webhook lo creó un script sin usuario |
Asegúrate de que el webhook pertenece a un administrador. El plugin de Provedly asigna uno cuando crea el webhook |
| "Invalid signature" en el registro de entregas |
Los secretos no coinciden |
Pega el mismo secreto en ambos lados |
| No llega nada |
El webhook está En pausa o Desactivado, o la URL de entrega tiene un error |
Ponlo en Activo y vuelve a copiar la URL |
| El webhook pasó solo a Desactivado |
WooCommerce desactiva un webhook tras varias entregas fallidas |
Arregla la causa y vuelve a ponerlo en Activo |
| Los pedidos llegan con minutos de retraso |
Las entregas se ponen en cola como tareas en segundo plano que se ejecutan cuando el sitio recibe tráfico o una tarea programada |
Revisa WooCommerce, Estado, Acciones programadas en busca de tareas de webhook pendientes |
| Aparecen pedidos sin pagar en otra herramienta |
El tema es order.created y la herramienta no comprueba el estado |
Usa order.updated y filtra por estado |
WooCommerce guarda un registro de las entregas en WooCommerce, Estado, Registros. Muestra la respuesta que devolvió el servicio receptor, y suele ser la forma más rápida de ver qué salió mal.
Cuando creas un webhook nuevo, WooCommerce envía un breve "ping" de prueba a la URL de entrega. Un receptor bien hecho lo responde para que el webhook pueda activarse; no contiene ningún pedido.
Cómo hacerlo con Provedly
No tienes que configurar nada de esto a mano. El plugin gratuito de Provedly crea el webhook cuando pegas la URL de entrega y el secreto en su página de ajustes y haces clic en Guardar: tema order.updated, versión actual de la API, activo, firmado con tu secreto y propiedad de un administrador. Nuestra guía de notificaciones de ventas recientes en WooCommerce recorre la configuración.
Preguntas frecuentes
¿Necesito un secreto en mi webhook de WooCommerce?
No para que WooCommerce lo envíe, pero siempre deberías poner uno cuando el receptor lo admite. Sin él, el receptor no puede distinguir los mensajes de tu tienda de los de cualquier otro, y una notificación de ventas basada en mensajes sin firmar no puede llamarse verificada con honestidad.
¿Puedo tener más de un webhook para pedidos?
Sí. Cada servicio tiene su propio webhook con su propia URL de entrega y su propio secreto. No interfieren entre sí, y pausar uno deja los demás funcionando.
¿Un webhook nuevo enviará mis pedidos antiguos?
No. Un webhook se dispara con eventos que ocurren después de que existe, así que los pedidos antiguos solo se envían si cambian, por ejemplo cuando marcas uno como Completado. Para traer el historial, usa la opción de importación del servicio receptor.
Conecta tus pedidos de WooCommerce por un webhook firmado con el plan gratis de Provedly creando una cuenta.