Webhooks en la Buyer API

​

Configurar un endpoint

• la URL HTTPS que debe recibir las entregas,
• cuáles de los tres eventos quieres (workorder.create, workorder.status_update, workorder.new_note), y
• si el endpoint es de pruebas o de producción.

​

Eventos

• workorder.create se dispara en cada creación, sin importar quién la haga: tu propio POST /v1/buyer/work_order/work_orders, un usuario en las apps web o móviles de OpenWrench, un cronograma de mantenimiento preventivo, un recorrido de encuesta de sitio, o un proveedor que abre una orden de trabajo en una de tus ubicaciones (SupplierInitiatedPendingApproval). El payload lleva el estado inicial, así que puedes distinguir una solicitud de servicio pendiente de aprobación de una orden de trabajo despachada al crearse.
• workorder.status_update se dispara en cada transición del modelo de estados, para estados propiedad de cualquiera de los dos lados. Las ediciones que no tocan status (un cambio de prioridad, una nueva fecha estimada de finalización, una reasignación mientras la orden sigue pendiente de confirmación) no emiten uno. Cuando una orden de trabajo pasa de un proveedor a otro puedes recibir una actualización intermedia cuyo newStatus es Rejected, que cierra la asignación anterior, seguida de la actualización con el estado nuevo.
• workorder.new_note se dispara para las notas del hilo raíz comprador–proveedor de cualquiera de los dos lados, incluidas las notas publicadas por tu propia integración, las publicaciones masivas de fotos y la nota adjunta a una acción de estado. Las notas internas de los proveedores y los hilos de subcontratación nunca emiten eventos.

​

Payload de la entrega

​

Eventos de creación y de estado

{
  "event_type": "workorder.status_update",
  "data": {
    "workOrderId": 9001,
    "location": "Store 1204 - Denver",
    "oldStatus": "TechScheduled",
    "newStatus": "WaitingForReview",
    "changedBy": "Sam Rivera",
    "changedAt": "2026-08-21T09:05:22.000-07:00"
  }
}

​

Eventos de nota

{
  "event_type": "workorder.new_note",
  "data": {
    "workOrderId": 9001,
    "newNote": "Access code for the back door is 4417.",
    "addedBy": "Sam Rivera",
    "addedAt": "2026-08-21T09:05:22.000-07:00"
  }
}

​

Verificar las entregas

​

Respuesta, reintentos y duplicados

• Confirma rápido. Devuelve un 2xx en cuanto hayas almacenado el evento, y haz el trabajo posterior (obtener la orden de trabajo, actualizar tu sistema) de forma asíncrona. Una respuesta distinta de 2xx o un tiempo de espera agotado cuentan como entrega fallida.
• Las entregas fallidas se reintentan desde la pasarela con un esquema de espera creciente. Haz que tu manejador sea idempotente para que un reintento tras un éxito parcial no cause daño.
• Las entregas son al menos una vez. El mismo evento puede llegar más de una vez incluso sin un fallo de tu lado. Deduplica con event_type más workOrderId más changedAt (o addedAt para las notas).
• El orden no está garantizado. Dos eventos de la misma orden de trabajo pueden llegar desordenados. No derives el estado de la secuencia de eventos; obtén la orden de trabajo y confía en su status.
• Los eventos antiguos se descartan, no se entregan tarde. Un evento que no se haya pasado a la pasarela dentro de las tres horas siguientes al cambio se descarta. Tras una interrupción del lado de OpenWrench, o si tu endpoint estuvo caído más tiempo que la ventana de reintentos, concilia sondeando GET /v1/buyer/work_order/work_orders?statusChangedAt=... para el periodo que te perdiste.

​

Reaccionar a un evento

# Obtener la orden de trabajo indicada en el evento
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders/9001"

​

Juntándolo todo

1. Registra un endpoint para workorder.create y workorder.status_update (añade workorder.new_note si replicas la conversación).
2. En workorder.create, obtén la orden de trabajo y crea el registro correspondiente en tu sistema. Si despachas desde tu lado, haz PATCH del supplierFacilityId como se describe en Órdenes de trabajo.
3. En workorder.status_update, obtén la orden de trabajo. Cuando newStatus sea WaitingForReview, ejecuta tu flujo de revisión y publica work_reviewed_and_completed o work_unsatisfactory.
4. Ejecuta un sondeo periódico sobre statusChangedAt como red de seguridad para cualquier cosa que la ruta de webhooks haya perdido.