Eventos durables y webhooks firmados

Suscribirse

Registra hasta 20 URLs públicas HTTPS en el puerto 443 y hasta 30 tipos por suscripción. No se aceptan direcciones privadas, loopback, link-local ni destinos que resuelvan hacia ellas. Usa tipos específicos o *. El secreto whsec_… se muestra al crear o rotar y la rotación entra en vigor inmediatamente.

Verificar una entrega

Moku envía Moku-Event-Id, Moku-Delivery-Id y Moku-Signature: t=<unix>,v1=<hex>. Calcula HMAC-SHA256 con el secreto completo sobre timestamp + "." + cuerpo_crudo, compara en tiempo constante y rechaza timestamps antiguos.

const signed = timestamp + "." + rawBody;
const expected = createHmac("sha256", signingSecret)
  .update(signed)
  .digest("hex");
timingSafeEqual(Buffer.from(expected), Buffer.from(receivedV1));

El cuerpo del evento contiene metadatos del recurso, no su snapshot completo; consulta el endpoint del recurso para obtener el estado actual.

Entrega y reintentos

• Responde cualquier 2xx dentro de 5 segundos.
• Cada destino se procesa de forma independiente. Una URL lenta o fallida no obliga a repetir entregas exitosas a otros destinos.
• Los fallos se reintentan hasta 10 intentos con backoff desde 30 segundos y tope de una hora.
• Una reproducción manual puede generar duplicados y no usa clave de idempotencia.
• Deduplica por event.id; Moku-Delivery-Id es estable por evento y suscripción, incluso al reproducir.
• Las entregas pueden llegar fuera de orden; usa la versión del recurso y consulta su estado vigente.
• Ignora campos y tipos futuros desconocidos.

Reproducir y consultar el resultado

POST /vendors/{vendor_id}/events/{event_id}/replay responde 202 Accepted cuando el trabajo quedó guardado, no cuando terminó la entrega. Guarda replay_id y consulta:

GET /vendors/{vendor_id}/events/{event_id}/replays/{replay_id}

Necesitas webhooks.write para iniciar y webhooks.read para consultar. El estado avanza entre queued, running, completed o failed. total es null hasta seleccionar los destinos. Los contadores delivered, failed y skipped permiten distinguir resultados parciales; una suscripción eliminada o desactivada se omite.

Cada POST crea una reproducción nueva. Si pierdes la respuesta, no asumas que el primer intento falló: repetirlo puede duplicar entregas.

Tipos publicados en v1

• product.created
• product.updated
• product.published
• product.unpublished
• product.archived
• product.restored
• inventory_item.adjusted
• inventory_item.reserved
• inventory_item.consumed
• inventory_item.released
• inventory_item.restocked
• inventory_item.reference_price_updated
• inventory_item.review_required
• inventory_reservation.created
• inventory_reservation.renewed
• inventory_reservation.committed
• inventory_reservation.released
• inventory_reservation.expired
• connection.created
• connection.updated
• connection.roles_changed
• connection.disconnected
• connection.reconnected
• channel_listing.created
• channel_listing.updated
• channel_listing.ended
• external_order.created
• external_order.updated
• external_order.reconciliation_required
• external_order.terminal_resolved
• external_order.reservation_renewed
• seller_order.paid
• seller_order.fulfillment_updated
• seller_order.cancelled
• webhook_subscription.created
• webhook_subscription.updated
• webhook_subscription.deleted
• webhook_subscription.secret_rotated
• sync_job.queued
• sync_job.succeeded
• sync_job.failed
• bulk_operation.queued
• bulk_operation.completed
• integration_conflict.created
• integration_conflict.updated
• integration_conflict.reopened
• integration_conflict.resolved
• stock_effect.created
• stock_effect.confirmed
• stock_effect.blocked