Browse all articles

Configurar webhooks en ChannelDock

Last updated

¿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. Cuando hay un secreto configurado, ChannelDock firma cada entrega con una firma HMAC-SHA256 en la cabecera X-Channeldock-Signature, de modo que pueda verificar que una solicitud proviene realmente de ChannelDock.

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.picking, order.picked, 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 (opcional pero recomendado): Indique su propio secreto o haga clic en Generar para crear un secreto robusto. ChannelDock usa este secreto para firmar cada entrega, de modo que pueda verificar que la solicitud viene de ChannelDock y que no se modificó en el camino.

  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 se produce el evento elegido, ChannelDock envía un payload JSON a su endpoint. El payload contiene al menos los siguientes campos:

{   
  "event": "order.created",  
  "payload": {   
    ...  
  },  
  "signature": "<hash>" (obsoleto, ver más abajo)  
}
  • event – el evento para el que se configuró el webhook (por ejemplo order.created).
  • payload – contiene los detalles del pedido, el envío, la devolución o el movimiento de stock. La estructura coincide con la respuesta de la API para el objeto correspondiente.
  • signature – solo está presente cuando hay un secreto configurado. Es la firma antigua y está obsoleta; verifique en su lugar la cabecera X-Channeldock-Signature.

Verificar la firma

La URL de su webhook debe ser accesible públicamente, y la solicitud no contiene ninguna otra prueba de quién la envió: ni clave de API, ni contraseña. Por tanto, todo lo que llegue a esa URL le parecerá a su endpoint una entrega real de ChannelDock: una URL filtrada por un archivo de log, un proxy o un ticket de soporte, o una entrega anterior que alguien capturó y volvió a enviar. Si actúa sobre el contenido sin comprobarlo, un stock.updated falso podría dejar su stock a cero, o un order.updated falso marcar un pedido como enviado en su propio sistema.

La firma es esa prueba que falta. Solo usted y ChannelDock conocen el secreto, así que solo ustedes dos pueden producir un valor que coincida con la entrega que tiene delante.

En cuanto configura un secreto de webhook, cada entrega de ese webhook llega con una cabecera HTTP adicional:

X-Channeldock-Signature: sha256=8b415f2c0cd241a21109e007942b6ce43cbfcf97f7b2d7829084258c0ae0a66f

Ese valor es un hash HMAC-SHA256 del cuerpo de la solicitud, calculado con su secreto como clave. Usted calcula el mismo hash por su parte y comprueba que ambos son idénticos. Si no hay secreto configurado, la cabecera no se envía.

Verificar la firma en su aplicación

  1. Lea el cuerpo en bruto. Tome el cuerpo de la solicitud como texto o bytes, antes de que se analice el JSON. La mayoría de los frameworks analizan el JSON y descartan el texto original, así que pídalo explícitamente: php://input en PHP, $request->getContent() en Laravel, request.get_data() en Flask, request.body en Django, request.raw_post en Rails, o express.json({ verify: (req, res, buf) => { req.rawBody = buf } }) en Express.
  2. Lea la cabecera. Tome X-Channeldock-Signature y quite el prefijo sha256=. Busque la cabecera sin distinguir mayúsculas y minúsculas: según la conexión puede llegar como x-channeldock-signature.
  3. Calcule su propio hash. Un HMAC-SHA256 del cuerpo en bruto con su secreto de webhook como clave, escrito en hexadecimal. En PHP: hash_hmac('sha256', $raw, $secret).
  4. Compare con una función de tiempo constante como hash_equals. Si ambos son idénticos, la entrega es auténtica y puede procesarla. Si no, devuelva HTTP 401 e ignore el cuerpo. Analice el JSON solo después de que este paso tenga éxito.

Importante: aplique el hash al cuerpo exactamente como lo recibió. Una firma es un hash de bytes, no del significado del JSON. Por tanto, no analice el JSON para volver a convertirlo en texto y aplicarle el hash. Dos lenguajes pueden escribir un JSON que significa exactamente lo mismo pero no es el mismo texto: PHP escribe una barra como c\/o donde Node.js y Python escriben c/o. Eso se relee como datos idénticos, pero produce un hash completamente distinto. Tampoco quite el campo signature antes de aplicar el hash: forma parte del cuerpo que se firmó.

El campo signature obsoleto

Antes de que existiera la cabecera, ChannelDock ponía un campo signature en el propio cuerpo. Se sigue enviando sin cambios, así que las integraciones existentes continúan funcionando, pero está obsoleto. Verificarlo implica quitar el campo y reconstruir el resto del JSON como texto exactamente como lo escribe PHP, incluida su costumbre de escribir / como \/. En otro lenguaje eso es casi imposible de acertar.

Desarrolle las nuevas integraciones sobre la cabecera. Si hoy verifica el campo, nada se rompe: ambos se envían en cada entrega, así que puede cambiar cuando le convenga. Los dos valores nunca son iguales, porque cubren datos distintos; nunca los compare entre sí.

Consejos para un procesamiento seguro

  • Asigne a cada webhook su propio secreto y rótelo con regularidad.
  • Use una función de comparación de tiempo constante (por ejemplo hash_equals en PHP o crypto.timingSafeEqual en Node.js) para prevenir ataques de temporización.
  • Verifique la firma antes de actuar sobre el contenido del payload.
  • Realice comprobaciones adicionales sobre el 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.

Was this helpful?