• 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

    Hi Devon! Happy to help clarify this — the webhook payload structure has evolved and I know the documentation hasn't kept pace in all places.

    For status change events specifically:

    1. Always use work_order_id — job_id is legacy terminology that shouldn't appear in v2.x webhooks
    2. The work_order.status_changed event sends a delta payload, not the full object. If you need the complete work order, you'll want to subscribe to work_order.updated or make a follow-up API call
    3. Previous status — this is available in the context object, but only when the change originates from the web application. Mobile and API updates don't currently populate this. We're tracking this gap internally

    Regarding your environment differences:

    You're correct — sandbox environments are running an older webhook version. The technician_ids array format is the current standard in production (v2.1). You can request a sandbox refresh to v2.1 through your CSM, or code defensively as Eli suggested.

    For the photo upload race condition:

    This is a known limitation. The work_order.completed event fires on status transition, not media completion. For your CMDB sync use case, I'd recommend:

    1. Subscribe to work_order.status_changed
    2. Filter for status: "completed"
    3. Queue a delayed job (30-60 seconds) or poll the Work Orders API to verify attachments before notifying Slack

    I've attached this to your account notes and we'll follow up when the attachments-complete event moves to GA. Let me know if you need a canonical payload example for your security review!

Reply
  • 0

    Hi Devon! Happy to help clarify this — the webhook payload structure has evolved and I know the documentation hasn't kept pace in all places.

    For status change events specifically:

    1. Always use work_order_id — job_id is legacy terminology that shouldn't appear in v2.x webhooks
    2. The work_order.status_changed event sends a delta payload, not the full object. If you need the complete work order, you'll want to subscribe to work_order.updated or make a follow-up API call
    3. Previous status — this is available in the context object, but only when the change originates from the web application. Mobile and API updates don't currently populate this. We're tracking this gap internally

    Regarding your environment differences:

    You're correct — sandbox environments are running an older webhook version. The technician_ids array format is the current standard in production (v2.1). You can request a sandbox refresh to v2.1 through your CSM, or code defensively as Eli suggested.

    For the photo upload race condition:

    This is a known limitation. The work_order.completed event fires on status transition, not media completion. For your CMDB sync use case, I'd recommend:

    1. Subscribe to work_order.status_changed
    2. Filter for status: "completed"
    3. Queue a delayed job (30-60 seconds) or poll the Work Orders API to verify attachments before notifying Slack

    I've attached this to your account notes and we'll follow up when the attachments-complete event moves to GA. Let me know if you need a canonical payload example for your security review!

Children
No Data