• State Verified Answer
  • Replies 7 replies
  • Subscribers 2 subscribers
  • Views 11 views
  • Users 0 members are here
Options
Related

Webhook payload structure for job status changes

Devon Marsh

Hey team — I'm building out a notification pipeline that needs to fire when work orders hit specific status transitions (Created → Assigned → In Progress → Completed, etc.).

I've got webhooks configured and hitting my endpoint, but the payload structure I'm receiving doesn't seem to match what's in the webhook setup guide. Specifically:

  • Is job_id always present, or only for certain event types?
  • Does the payload include the full work order object, or just the delta/changed fields?
  • Are status transition events (work_order.status_changed) supposed to include the previous status value somewhere? I'm seeing status but not previous_status or similar.

Also heads up — I'm seeing inconsistent behavior between the sandbox and prod environments. Sandbox payloads include a technician_ids array, but prod is sending assigned_to as a single string. YMMV warning here.

My use case: need to sync status changes to an external CMDB and trigger Slack notifications when jobs hit "Completed." The work_order.completed event seems to fire before photos finish uploading sometimes, which is... not ideal for our downstream workflow.

Anyone got a canonical payload example for work_order.status_changed? Or should I be subscribing to individual status events instead of the generic change event?

Parents
  • 0

    yeah this one tripped me up too when I first looked at it

    so the work_order.status_changed event is actually a bit of a trap — it's generic by design but the payload structure depends on what triggered the change. here's what I've seen:

    {
  "event": "work_order.status_changed",
  "timestamp": "2025-09-17T10:15:00Z",
  "data": {
    "work_order_id": "wo_abc123",
    "status": "completed",
    // previous_status is NOT guaranteed — see below
    "changed_by": {
      "user_id": "usr_def456",
      "source": "mobile_app" // or "web", "api", "system"
    },
    "technician_ids": ["tech_ghi789"], // array in v2.1+, string in legacy
    "context": {
      // sometimes has previous_status here, sometimes doesn't
    }
  }
}

    the previous_status thing is annoying — it's in the context object when the change comes from the web app, but missing when it comes from mobile sync. I opened a ticket about this a while back, still waiting.

    worth noting: if you need reliable state comparison, you really should cache the previous state yourself. I know, I know, but that's the workaround rn.

    also re: the completed event firing early — that's a known race condition with photo uploads. the event fires when status transitions, not when all attachments finish. there's a separate work_order.attachments_complete event in beta that might help? v2.1 webhook improvements mentions it briefly.

Reply
  • 0

    yeah this one tripped me up too when I first looked at it

    so the work_order.status_changed event is actually a bit of a trap — it's generic by design but the payload structure depends on what triggered the change. here's what I've seen:

    {
  "event": "work_order.status_changed",
  "timestamp": "2025-09-17T10:15:00Z",
  "data": {
    "work_order_id": "wo_abc123",
    "status": "completed",
    // previous_status is NOT guaranteed — see below
    "changed_by": {
      "user_id": "usr_def456",
      "source": "mobile_app" // or "web", "api", "system"
    },
    "technician_ids": ["tech_ghi789"], // array in v2.1+, string in legacy
    "context": {
      // sometimes has previous_status here, sometimes doesn't
    }
  }
}

    the previous_status thing is annoying — it's in the context object when the change comes from the web app, but missing when it comes from mobile sync. I opened a ticket about this a while back, still waiting.

    worth noting: if you need reliable state comparison, you really should cache the previous state yourself. I know, I know, but that's the workaround rn.

    also re: the completed event firing early — that's a known race condition with photo uploads. the event fires when status transitions, not when all attachments finish. there's a separate work_order.attachments_complete event in beta that might help? v2.1 webhook improvements mentions it briefly.

Children
No Data