Webhooks en la Supplier 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 significa “trabajo nuevo para ti”, no solo “se creó una fila nueva”. Se dispara cuando se crea una orden de trabajo con tu instalación asignada, cuando un comprador te reasigna una orden de trabajo existente (entra en PendingConfirmationByServiceProvider) y cuando tú mismo abres una orden de trabajo iniciada por el proveedor (SupplierInitiatedPendingApproval). Una orden de trabajo creada para ti que primero necesita la aprobación interna del comprador emite workorder.create cuando alcanza PendingConfirmationByServiceProvider, no cuando el aprobador del comprador la ve por primera vez.
• workorder.status_update se dispara cuando una orden de trabajo asignada a ti entra en ConfirmedByServiceProvider, TechAssigned, TechScheduled, TechRescheduled, WorkIncompleteWithReason (salvo que venga directamente de TechWorkingOnSite, que es un check-out), WorkUnsatisfactory, WorkReviewedAndCompleted, CancelledWithReason o PaymentMade. Eso cubre tu propia aceptación, la programación que hacen tus técnicos en las apps de OpenWrench y las decisiones del comprador sobre tu trabajo. Los estados de partes, TechEnRoute, TechWaitingOnSite, TechWorkingOnSite, WaitingForReview y los estados de cotización y propuesta no emiten eventos.
• 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. Tus notas internas y los hilos de las órdenes de trabajo que subcontratas nunca emiten eventos.

• Reasignación fuera de ti. Si el comprador mueve una orden de trabajo a otro proveedor, simplemente desaparece de tu cola. Concilia contra GET /v1/supplier/work_order/work_orders si eso te importa.
• Órdenes de trabajo que solo puedes ver. Si tu instalación está en la lista de visibilidad de una orden de trabajo en lugar de asignada a ella, recibes sus eventos solo si OpenWrench ha habilitado los webhooks de visibilidad para tu empresa. Pregunta a soporte si lo necesitas.

​

Payload de la entrega

​

Eventos de creación y de estado

{
  "event_type": "workorder.create",
  "data": {
    "workOrderId": 9001,
    "customer": "Acme Grocery",
    "location": "Store 1204 - Denver",
    "newStatus": "PendingConfirmationByServiceProvider",
    "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/supplier/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/supplier/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 trabajo en tu sistema. Luego ramifica según newStatus: PendingConfirmationByServiceProvider significa que el comprador te espera, así que haz confirm o decline dentro de tu SLA; SupplierInitiatedPendingApproval significa que tu propia solicitud espera al comprador, así que no hagas nada hasta que un workorder.status_update informe el resultado; cualquier otro estado significa que la orden de trabajo ya es tuya, así que pasa directamente a la programación.
3. En workorder.status_update, obtén la orden de trabajo. WorkUnsatisfactory y WorkReviewedAndCompleted te dan el veredicto del comprador; CancelledWithReason cierra el trabajo; PaymentMade cierra la parte económica.
4. Ejecuta un sondeo periódico sobre assignedAt o statusChangedAt como red de seguridad para cualquier cosa que la ruta de webhooks haya perdido, incluido el trabajo reasignado fuera de ti.