¿Por qué usar webhooks?

ChannelDock proporciona webhooks para informar a su sistema inmediatamente cuando algo cambia en su cuenta. En lugar de consultar la API según un calendario, recibe automáticamente una notificación cuando se crea o actualiza un pedido, se crea un envío, cambian los niveles de stock o se registra una devolución. Los webhooks le ayudan a automatizar procesos y reducir solicitudes API innecesarias.

Características clave

• Momento del evento: Los webhooks se activan unos minutos después de que ocurre un evento, ofreciéndole actualizaciones casi en tiempo real.
• Coherencia del payload: El payload JSON de un webhook coincide con la estructura devuelta por el endpoint API correspondiente.
• Reintentos automáticos: Si ChannelDock no puede entregar un webhook, se realizan hasta cinco intentos con retrasos crecientes (0, 30, 60, 120 y 240 segundos). Tras diez entregas fallidas, el webhook se desactiva por seguridad.
• Seguridad: Cada webhook puede tener su propia clave secreta. ChannelDock usa esta clave secreta para calcular una firma digital para que pueda verificar la autenticidad del payload.

Configurar un webhook

1. Acceda a la configuración: Inicie sesión en ChannelDock y vaya a Settings → API & Webhooks. Verá dos secciones: API keys y Webhooks.

2. Cree un nuevo webhook: Haga clic en Create new webhook. Aparece una ventana « Webhook Configuration ».

3. Complete los campos:

   • Webhook name: Elija un nombre interno descriptivo (por ejemplo, « Order updates »).
   • Webhook URL: Introduzca la URL de su endpoint donde ChannelDock puede enviar una solicitud HTTP POST. Asegúrese de que esta URL sea accesible públicamente y responda en 5 segundos.
   • Event to trigger webhook: Seleccione el tipo de evento para el que desea notificaciones. Los eventos posibles incluyen order.created, order.updated, order.status.changed, order.deleted, shipment.created, stock.updated, return.created, return.handled y return.product.updated.
   • Status: Déjelo en Active. Los webhooks se desactivan automáticamente tras 10 intentos de entrega fallidos.
   • Webhook secret (optional but recommended): Proporcione su propio secret o haga clic en Generate para crear uno robusto. ChannelDock usa este secret para calcular una firma hash HMAC‑SHA256 para que pueda verificar el payload.

4. Guarde: Haga clic en Save webhook. ChannelDock almacena su webhook y enviará eventos del tipo seleccionado a su endpoint.

Estructura del payload y eventos

Cuando ocurre un evento elegido, ChannelDock envía un payload JSON a su endpoint. El payload contiene al menos los campos siguientes:

{   
  "event": "order.created",  
  "payload": {   
    ...  
  },  
  "signature": "<hash>" (Optional but recommended)  
}

• event – el evento para el que se configuró el webhook (por ejemplo order.created).
• payload – contiene detalles del pedido, envío, devolución o mutación de stock. La estructura coincide con la respuesta API del objeto correspondiente.
• signature – solo presente cuando hay un secret configurado. Es una firma HMAC‑SHA256 del payload completo, excepto el campo signature en sí.

Verificar la firma

Es importante asegurarse de que el webhook fue enviado por ChannelDock y que el payload no ha sido alterado. Para ello, compare la firma proporcionada por ChannelDock con su propio cálculo.

Internamente, ChannelDock firma cada payload calculando un hash HMAC‑SHA256 de los datos JSON con el secret que configuró. El hash resultante se añade como campo signature en el payload.

Verificar la firma en su aplicación

1. Reciba el webhook: Analice el JSON y almacene temporalmente el valor del campo signature. Elimine el campo signature del payload antes de calcular el hash.
2. Genere un hash: Use su secret key junto con el método de hash HMAC-SHA256 para crear una nueva firma. Ejecútelo sobre los datos JSON recibidos (sin el campo signature).
3. Compare los hash: Si el hash calculado coincide exactamente con la firma recibida, puede confiar en que el payload es auténtico y no modificado.

Consejos para un procesamiento seguro

• Asigne a cada webhook su propio secret y rótelos regularmente.
• Use una función de comparación en tiempo constante (por ejemplo hash_equals en PHP) para prevenir ataques de temporización.
• Realice comprobaciones adicionales del contenido del payload (por ejemplo verifique que el pedido existe) antes de ejecutar acciones.

Buenas prácticas

ChannelDock recomienda varias prácticas para procesar webhooks de forma segura y fiable:

• Respuesta HTTP‑200: Haga que su endpoint devuelva un HTTP 200 OK en cuanto el payload se haya recibido correctamente. De lo contrario, ChannelDock considera el intento fallido y reintenta.
• Idempotencia: Los mensajes webhook pueden enviarse a veces dos veces (por ejemplo por problemas de red o reintentos). Asegúrese de que su lógica de procesamiento sea idempotente para que los mensajes duplicados no provoquen trabajo duplicado.
• Monitorización: Use el panel de ChannelDock para monitorizar el estado de sus webhooks e identificar errores.
• Gestión del payload: Asegúrese de que su endpoint puede manejar payloads grandes y responde en un tiempo razonable (≤ 5 segundos). Los webhooks se desactivan automáticamente tras diez entregas fallidas.