¿Qué es un webhook?

Cuando una app te promete que «se entera al momento» de lo que cambias en tu tienda, casi siempre habla de webhooks. Un webhook no es una API a la que preguntas, ni un trozo de código que se instala en el tema: es un aviso que la plataforma envía a otra aplicación cuando pasa algo, sea un pedido nuevo o un precio cambiado. Te importa porque de esos avisos depende que tu feed, tu PIM o tu herramienta de marketing tengan el mismo precio que tu ficha, y porque los avisos, a veces, no llegan.

Cómo funciona

La aplicación que quiere enterarse se suscribe a un tipo de evento y da una dirección. Cuando el evento ocurre, la plataforma le envía los datos. Shopify lo explica con los pedidos: en lugar de consultar la API una y otra vez para ver si hay pedidos nuevos, la app se suscribe al tema orders/create y Shopify le envía cada pedido cuando se crea. Sus webhooks entregan datos casi en tiempo real, sirven para mantenerse sincronizado con la tienda o para lanzar otra acción, y pueden ir a una URL, a Google Pub/Sub o a Amazon EventBridge.⁠^{[1]Shopify Dev Docs. About webhooks}

En BigCommerce, una suscripción se crea con una petición POST a /v3/hooks.⁠^{[2]BigCommerce Docs. Webhooks} Para el catálogo hay eventos de producto creado, actualizado y borrado, de cambios de inventario y de metafields del producto o de sus variantes. El evento store/product/updated salta cuando cambian, entre otros, el precio, las dimensiones, la disponibilidad, la descripción, el nombre, el SKU, la visibilidad o los datos de envío.⁠^{[3]BigCommerce Docs. Webhook events}

Lo que llega en el aviso cambia mucho de una plataforma a otra. BigCommerce manda avisos ligeros a propósito: el de un cambio de estado de un pedido trae solo su identificador, y para ver el pedido hay que pedírselo a la API.⁠^{[2]BigCommerce Docs. Webhooks} El de un producto actualizado trae su identificador y la lista de propiedades que cambiaron.⁠^{[3]BigCommerce Docs. Webhook events}

Tres detalles operativos deciden si un webhook funciona en la práctica:

• La firma. Cada entrega de Shopify lleva la cabecera X-Shopify-Hmac-Sha256, que sirve para comprobar que el aviso viene de Shopify, y X-Shopify-Webhook-Id, para reconocer las entregas repetidas.⁠^{[1]Shopify Dev Docs. About webhooks}
• La respuesta. Tu servidor tiene que contestar en menos de cinco segundos con un código de la serie 200 para que Shopify dé la entrega por buena. Si no, reintenta hasta ocho veces en cuatro horas, y si los fallos siguen, elimina la suscripción.⁠^{[4]Shopify Dev Docs. Troubleshooting webhooks} BigCommerce también espera un 200; reintenta con intervalos cada vez más largos y, tras el último fallo, desactiva el webhook y avisa por correo a la app suscrita.⁠^{[2]BigCommerce Docs. Webhooks}
• El orden. Shopify no garantiza el orden de los avisos, ni dentro de un mismo tema ni entre temas distintos.⁠^{[1]Shopify Dev Docs. About webhooks}

Evento frente a sincronización periódica

La frase que más importa de la documentación de Shopify es una advertencia: un webhook no siempre llega, y una app no debería depender solo de recibirlos. Su recomendación es añadir tareas de conciliación que consulten la tienda cada cierto tiempo, filtrando por la fecha de actualización para pedir solo lo que cambió.⁠^{[1]Shopify Dev Docs. About webhooks} Así que la pregunta no es webhook o sincronización periódica, sino cómo se reparten el trabajo:

Con los dos, el aviso da la velocidad y la pasada periódica corrige lo que el aviso perdió. Sin la pasada, cada aviso perdido es una diferencia que nadie ve, y esas diferencias se acumulan hasta convertirse en deriva de datos.

En una tienda

Este es el aviso de ejemplo que publica BigCommerce para un producto actualizado:⁠^{[3]BigCommerce Docs. Webhook events}

{
  "scope": "store/product/updated",
  "store_id": "1025646",
  "data": {
    "type": "product",
    "id": 205,
    "properties": ["warranty", "is_featured", "custom_fields"],
    "context": { "channel_id": 2, "locale": "fr" }
  },
  "hash": "a833a57fadd56a32dc752fb6ca0841dc9602a495",
  "created_at": 1561479233,
  "producer": "stores/{store_hash}"
}

No trae la garantía nueva, ni los campos personalizados nuevos: trae el producto 205 y los nombres de lo que cambió. La app que lo recibe tiene que pedir el producto a la API de catálogo para saber los valores.⁠^{[2]BigCommerce Docs. Webhooks}

Ahora un ejemplo ficticio de lo que pasa cuando falla. Una tienda de trípodes cambia el precio de un modelo en su PIM, que lo escribe en BigCommerce. La app que genera el feed para un comparador está suscrita a store/product/updated, pero su servidor está caído esa tarde. BigCommerce reintenta durante horas y, tras el último fallo, desactiva la suscripción y manda un correo a la dirección de la app.⁠^{[2]BigCommerce Docs. Webhooks} Si nadie lee ese correo y la app no tiene una pasada periódica, el feed sigue con el precio viejo, y también todos los cambios que vengan después, porque ya no llega ningún aviso.

Cómo comprobarlo

1. Pide a cada app conectada a tu tienda la lista de eventos a los que está suscrita y qué hace con cada uno. Si no usa webhooks, pregunta cada cuánto consulta la tienda.
2. Pregunta si la app tiene una pasada periódica de conciliación, y cada cuánto corre. Es lo que Shopify recomienda para no depender solo de los avisos.⁠^{[1]Shopify Dev Docs. About webhooks}
3. Si la app es tuya, comprueba que verifica la firma de cada aviso con la cabecera X-Shopify-Hmac-Sha256 y que descarta los repetidos por X-Shopify-Webhook-Id.⁠^{[1]Shopify Dev Docs. About webhooks}
4. Mide cuánto tarda tu servidor en contestar: por encima de cinco segundos, Shopify da la entrega por fallida.⁠^{[4]Shopify Dev Docs. Troubleshooting webhooks}
5. En BigCommerce, vigila el buzón de la app: el correo de desactivación es el único aviso de que los avisos dejaron de llegar.⁠^{[2]BigCommerce Docs. Webhooks}

Concepto cercano: API de catálogo

La API de catálogo y el webhook son las dos direcciones de la misma conversación. Con la API, tu aplicación pregunta y la plataforma contesta; con el webhook, la plataforma avisa sin que nadie pregunte. Shopify presenta el webhook justo como la alternativa a consultar la API una y otra vez.⁠^{[1]Shopify Dev Docs. About webhooks} En BigCommerce trabajan juntos por diseño: el aviso dice qué producto cambió y la API dice cómo quedó.⁠^{[2]BigCommerce Docs. Webhooks} Si lo que te preocupa es quién escribió último un campo, eso es sobrescritura de campos, y si quieres poder volver atrás, versionado de contenido.

Para seguir, la ruta de lectura de publicación por plataforma ordena el resto de términos.