Guía de uso: webhooks

Guía de uso: webhooks

🔐 Introducción al Uso de Webhooks

Nuestra plataforma permite configurar webhooks para recibir actualizaciones automáticas sobre eventos clave relacionados con tus pedidos e incidencias. Esto te permite mantener tus sistemas sincronizados sin necesidad de realizar consultas manuales.

📌 ¿Qué son los Webhooks?

Un webhook es una llamada automática que nuestro sistema realiza a una URL que vos configures, cada vez que ocurre un evento relevante (como un cambio de estado en una orden o incidencia). De esta forma, tu sistema puede reaccionar de inmediato ante estos cambios.

🔑 Configuración Inicial

Para comenzar a utilizar los webhooks:
  1. Ingresá a la sección Mi Cuenta > Access Token.
  2. Creá una API Key con permisos sobre tus órdenes e incidencias.
  3. Configurá dos endpoints (URLs públicas):
  4. Uno para recibir actualizaciones de estado de órdenes.
  5. Otro para recibir actualizaciones de estado de incidencias.

✅ Seguridad: Firmas HMAC (opcional por ahora)

Para validar la autenticidad de los eventos que recibís, cada webhook puede incluir una firma digital en el header:
  1. Header: X-Dropea-Hmac-Sha256
  2. Contenido: un hash SHA256 generado usando el cuerpo del POST (payload) y tu API Key correspondiente como clave secreta.
Esto te permite verificar que la solicitud proviene realmente de nuestro sistema y no ha sido alterada, de forma similar a como lo hace Shopify en su sistema de webhooks.

⚠️ Importante: La validación mediante firma es opcional por el momento, pero se recomienda su implementación para reforzar la seguridad.

🛍️ Order Status Update

Cuando se actualiza el estado de una orden, el sistema envía una notificación al webhook configurado con la siguiente estructura de evento:

❌ Ejemplo 1: Pedido pasa de Confirmado a Cancelado (Payload a Recibir)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"confirmed","new_status":"cancelled","updated_at":"2025-05-29 14:14:58"}

✅ Ejemplo 2: Pedido pasa de Pendiente a Confirmado  (Payload a Recibir)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"pending","new_status":"confirmed","updated_at":"2025-05-29 14:14:58"}

🔁 Ejemplo 3: Pedido pasa de Error a Pendiente  (Payload a Recibir)
  1. {"topic":"order:status_update",
  2. "order_id":265496,"prev_status":"error","new_status":"pending","updated_at":"2025-05-29 14:38:05"}

🛠️ Incidence Update 

📌 Ejemplo: Incidencia pasa de Pendiente a Manejado por el Cliente (Payload a Recibir)
  1. {
  2.     "topic": "incidence:status_update",
  3.     "new_status": "client_managed",
  4.     "updated_at": "2025-02-13 14:23:56",
  5.     "prev_status": "pending",
  6.     "incidence_id": 189044
  7. }

🔄  Ejemplo 2:  Incidencia pasa de Pendiente a Solución Enviada
  1. {
  2.   "topic": "incidence:status_update",
  3.   "incidence_id": 265494,
  4.   "prev_status": "client_managed",
  5.   "new_status": "solution_send",
  6.   "updated_at": "2025-05-29 16:10:45"
  7. }

✅ Ejemplo 3: Incidencia pasa de Solución Enviada a Resuelto (Payload a Recibir)
  1. {
  2.   "topic": "incidence:status_update",
  3.   "incidence_id": 265494,
  4.   "prev_status": "solution_send",
  5.   "new_status": "resolved",
  6.   "updated_at": "2025-05-29 17:42:30"
  7. }

📌 Detalles por campo


Campo
TipoDescripción
topic
string
Puede ser "order:status_update" o "incidence:status_update", según el  origen del evento.
order_id
integer
ID de la orden afectada. Presente solo si topic es order:status_update.
incidence_id
integer
 ID de la incidencia afectada. Presente solo si topic es incidence:status_update.
prev_status
string
Estado anterior del objeto. Ej: "pending", "confirmed", "error".
new_status
string
Nuevo estado después del cambio.
updated_at
date
Fecha y hora del cambio. Este campo está en la zona horaria Europe/Madrid, que es:
 — UTC+2 en verano (horario de verano)
 — UTC+1 en invierno (horario estándar)



    • Related Articles

    • Guía de uso: API GraphQL de dropea con Apollo

      ? Generar API Key en dropea 1️⃣ Ve a Mi Cuenta → Access Tokens 2️⃣ Asigna un nombre a tu API Key ✏️ 3️⃣ Opcionalmente, puedes agregar una fecha de expiración. ⏳ (Si no la defines, la API Key será permanente) 4️⃣ Selecciona los permisos (scopes) que ...

    • ¿Dónde puedo encontrar una guía para comenzar a configurar mi cuenta de dropea?

      Una vez que ingreses a tu cuenta de dropshipper encontrarás una guía con los primeros pasos en la sección Dashboard del panel, en el menú lateral izquierdo (es la primera que aparece). Cada punto tiene su instructivo adjuntado y si haces click en ...

    • Notas dentro de los pedidos en dropea

      Las notas que dejas dentro de los pedidos en dropea NO las ve la empresa de reparto ni el proveedor, son solamente de uso interno. Si necesitas informarle algo a la empresa de reparto acerca de un pedido, debes comunicarte con el equipo de atención ...

    • Error de lectura de QR con autenticador de Google

      Si al momento de escanear el QR en dropea el autenticador de Google no te permite hacerlo, ingresa en las preferencias de la extensión y haz click en la opción "Sincronizar el reloj con Google" y vuelve a intentarlo.

    • Tasa de devolución de un pedido

      Tasa de devolución de un pedido Por un pedido devuelto se te cobra envío y fulfill de ida y de vuelta + IVA. El valor final dependerá del coste del envío y del fulfill + IVA que haya tenido dicho pedido. Recuerda que si el pedido no se entrega, el ...