Clarification on “manually_stacked” jobs and v2 job-created webhooks

Debugging & Troubleshooting
1

I came across your community post titled “Manually stacked – what happened to my order?” (https://community.stuart.engineering/t/manually-stacked-what-happened-to-my-order/233 which mentions receiving a job created webhook when orders are manually stacked by Stuart.

I have a few questions to clarify how this works:

  1. Is the “manually_stacked” workflow a client-specific configuration that needs to be enabled on our account, or does it happen automatically in some scenarios?

  2. The post references a “job created” webhook, which appears to belong to the v2 webhook format — could you confirm whether v2 webhooks are still being sent in this case, or if this behavior has been migrated to the v3 webhook events?

  3. If v2 webhooks are still being used for this event, what is the recommended v3 equivalent event or payload to track newly created jobs after a manual stacking operation?

  4. Are there any additional steps we need to take on our side (configuration, client reference setup, etc.) to ensure we correctly receive updates for manually stacked orders?

We want to make sure our integration handles these transitions correctly, especially since v2 webhooks are marked as deprecated.

2

Hello Taher,

Thank you for reaching out. I’ll take the time to look into your questions and will post an update as soon as possible.

Thank you in advance for your patience — we’re currently a bit short-handed, so there may be some delays.

Best regards,
Tasnim

3

Hi Taher

Thank you for your patience.

Here are my answers:

  1. About manual stacking
    Manual stacking is performed by our operations team via the back office when it’s estimated to be beneficial — for example, when two packages have close pickup or drop-off time windows, or when supply is limited.
    ➜ There’s nothing you need to do on your end to enable or support this workflow.

  2. Webhook version
    Webhooks v2 are deprecated, which means new enhancements are not always implemented for this version.
    Webhooks v3 is the most up-to-date version, including all recent features and improvements.
    While v2 is still supported, we strongly recommend migrating to v3 for better event consistency and long-term stability.
    :backhand_index_pointing_right: If you plan to migrate and would like assistance understanding the manual stacking webhook flow in v3, I’d be happy to help.

  3. What to expect when manual stacking occurs
    Assuming two packages are stacked together:

    • The initial two jobs and their deliveries (one job per package) are cancelled.

    • A new job is then created containing two deliveries.

    • Each delivery keeps the same client reference as before stacking.

    • Webhooks are sent as follows:

      • job.update events include a currentDelivery field identifying which delivery the update refers to (via its id and clientReference).

      • The job.update payload also lists all deliveries under that job.

      • delivery.update webhooks continue as before, but reference the new delivery IDs created during stacking.

Example webhook sequence

Here I created two deliveries, as follows:

  • Package 1:
    • Job ID = 299455993
    • Package ID = 308774702
    • Client reference = Test-manual-stacking-1762420846
  • Package 2:
    • Job ID = 299455997
    • Package ID = 308774706
    • Client reference = Test-manual-stacking-1762420857

Here is the webhook sequence sent after stacking both packages together:

Webhook topic Job ID Package ID Status Notes / Payload snippet
job.create 299455993 scheduled deliveries[0].id = 308774702, deliveries[0].clientReference = "Test-manual-stacking-1762420846"
delivery.create 308774702 pending data.clientReference = "Test-manual-stacking-1762420846"
job.create 299455997 scheduled deliveries[0].id = 308774706, deliveries[0].clientReference = "Test-manual-stacking-1762420857"
delivery.create 308774706 pending data.clientReference = "Test-manual-stacking-1762420857"
job.update 299455993 308774702 cancelled data.cancellation.reasonKey = "manually_stacked"
delivery.update 308774702 cancelled data.cancellation.reasonKey = "manually_stacked"
job.update 299455997 308774706 cancelled data.cancellation.reasonKey = "manually_stacked"
delivery.update 308774706 cancelled data.cancellation.reasonKey = "manually_stacked"
job.create 299456008 scheduled deliveries[0].id = 308774717, deliveries[1].id = 308774718
delivery.create 308774717 pending data.clientReference = "Test-manual-stacking-1762420846"
delivery.create 308774718 pending data.clientReference = "Test-manual-stacking-1762420857"
job.update 299456008 in_progress currentDelivery.id = 308774717, currentDelivery.status = picking

Tracking tip:
When tracking manually stacked packages, focus on the clientReference field created at delivery creation.
Since new delivery and job IDs are generated during stacking, using those IDs alone can make order tracking difficult — the client reference remains the reliable identifier across stacking operations.

Summary:

  • Manual stacking happens automatically — no client action required.

  • Webhook v2 still works but lacks newer enhancements.

  • We strongly recommend migrating to webhook v3, which includes the full, up-to-date manual stacking flow.

  • If you need help understanding or testing the v3 stacking webhook sequence, let me know — I’ll be glad to assist.

Best,
Tasnim

4

Hi,

Thank you for your response. That has made things more clear.

However, you mention the V2 webhooks are deprecated but in handling manual stacking, you appear to be using V2 webhooks (job.create, delivery.create). I cannot see these events as V3 webhooks? Stuart API

5

Hi Taher,

Following up on your question about how manual stacking is handled in webhook v3, here’s a detailed explanation based on the observed event flow.

When two packages are manually stacked by our operations team, the system first cancels the original packages and then creates new ones that reflect the updated (stacked) delivery structure.

Here’s what happens step by step:

  1. Initial package creation

    • package_created → Package 1 (id: 308871846, reference: Test-stacking-1762765455)

    • package_created → Package 2 (id: 308871874, reference: Test-stacking-1762765568)

  2. Manual stacking event occurs

    • Our operations team stacks the two packages together.

  3. Webhook sequence after stacking

    • The system first cancels both original packages:

      • package_canceled → Package 1 (id: 308871846, reason: manually_stacked)
      • package_canceled → Package 2 (id: 308871874, reason: manually_stacked)

    • Then, two new package_created events are sent to represent the new stacked configuration:

      • package_created → New Package A (id: 308871882, reference: Test-stacking-1762765455)

      • package_created → New Package B (id: 308871881, reference: Test-stacking-1762765568)

Each new package keeps the same client reference as before stacking, which allows you to link pre- and post-stacking events reliably, even though the package IDs have changed.

We recommend always using the reference field as the main identifier for tracking, as the id values are regenerated when stacking occurs.

The v3 webhook structure ensures full visibility of this flow — cancellations for the initial packages, followed by the creation of new packages under the updated delivery grouping.

This behavior has been verified and is consistent across manual stacking cases.

Best regards,
Tasnim