Webhooks

En lugar de consultar periódicamente, registra un endpoint HTTPS y Nembol te envía por POST un evento cada vez que ocurre algo: llega un pedido nuevo de cualquier canal, cambia el stock, un anuncio se publica o da error.

Crea endpoints en el panel (Configuración → Desarrolladores → Webhooks) o mediante la API. Cada endpoint tiene un secreto de firma, que se muestra una sola vez al crearlo.

La entrega

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Nembol-Webhooks/1.0 (+https://developers.nembol.com/docs/webhooks)
X-Nembol-Event-Id: evt_2c91…
X-Nembol-Signature: t=1784900412,v1=5257a869e7…

{
  "id": "evt_2c91…",
  "type": "order.created",
  "api_version": "2026-07-24",
  "store_id": "5f2a…",
  "account_id": "acct_66f0a1",
  "created_at": "2026-07-24T16:03:12Z",
  "data": {
    "object": { "id": "ord_…", "channel": "etsy", "total": "49.90", "currency": "USD" }
  }
}

account_id solo aparece para los partners, en todos los eventos de una de sus empresas (tanto en las entregas como en GET /events, incluido operation.completed): indica a qué empresa pertenece el evento (el mismo id que en GET /accounts). Los eventos de tu propia tienda no lo llevan. Enruta según este campo.

Cada entrega lleva User-Agent: Nembol-Webhooks/1.0 y el id del evento en X-Nembol-Event-Id. Fíate de la firma, no de estos headers: sirven para tus logs y tus reglas de firewall. Una entrega se envía una vez por endpoint (solo se repite en los reintentos tras una respuesta que no es 2xx, con el mismo id de evento).

data.object es el recurso completo tal como está cuando se entrega el evento (o cuando se lee desde GET /events), no una copia congelada en el momento del cambio. Lo que cambió está en el propio data: p. ej. data.status y data.previous_status en listing.status_changed. Si el recurso volvió a cambiar entretanto, data.object ya muestra el estado más reciente y llegará un evento posterior; ordena tus actualizaciones según el created_at del evento.

El contrato (léelo dos veces)

• Al menos una vez: el mismo evento puede entregarse más de una vez. Deduplica por event.id.
• Sin garantía de orden: los eventos pueden llegar desordenados. Usa created_at (o vuelve a leer el recurso) en lugar de suponer una secuencia.
• Se entregan todos los eventos, sea cual sea la parte de Nembol que los generó (llamada a la API, panel, sincronización de pedidos, webhook del canal). Si la entrega de un evento no pudo ponerse en cola al crearse, Nembol la pone en cola en pocos minutos (eventos de hasta 24 horas de antigüedad): llega tarde, pero nunca se pierde. Un endpoint solo recibe los eventos creados después de él. GET /events sigue siendo la vía de reconciliación.
• Tipos desconocidos: con el tiempo se añaden nuevos tipos de evento. Ignora los tipos que no gestionas y devuelve 2xx de todos modos.
• Responde rápido con 2xx: en menos de 10 segundos, o la entrega cuenta como fallida. Haz el trabajo real de forma asíncrona: ponlo en cola y luego devuelve 200.
• Verifica la firma antes de fiarte de nada: verifica las firmas.

Reintentos

Las entregas fallidas (respuesta que no es 2xx, timeout, error de conexión) se reintentan con backoff exponencial: 1m → 5m → 30m → 2h → 12h (unas 15 horas), y después la entrega se marca como fallida. Si un endpoint sigue fallando, se desactiva automáticamente y se avisa al propietario de la tienda en el panel y por email. Cada intento se ve en el registro de entregas del panel, con reenvío manual.

¿Te has perdido un periodo entero? Reconcilia con la API del registro de eventos: GET /events?created_after=… devuelve los eventos de los últimos 30 días.

Última actualización el 20 de octubre de 2026