How introduce a change in webhook payload with out breaking existing integration

Question

On occurrence certain event in our application resources like user/order/shipment , we are informing the subscribers about event occurrence with high level details of the event. Changes to the application resources like user/order/shipment can be performed via REST web api.

Now due to business requirement the existing webhook payload structure needs a change, introduce that change will break the existing integration. Any solution to introduce the webhook payload change without breaking any existing integration?

Sample existing webhook payload

{
  orderid : 123455,
  customerid : [email protected],
  other properties ....
}

Sample Future webhook payload

{
  orderid : 123455,
  customerid : 5435gd98, //modification
  other properties ....
}

Answer 1

Ideally, during designing the event schema, you should have a version property in your event which would denote the schema version like below. Whenever a subscriber hooks to your event, they will be tied to a specific version until they need to switch to a newer version. In that way, every time you transition to a new schema, you continue to maintain both old and new for certain grace period for backward compatibility to allow your existing subscribers to update without disruption.

{
  version : 1,
  orderid : 123455,
  customerid : [email protected],
  other properties ....
}

{
  version : 2,
  orderid : 123455,
  customerid : 5435gd98, //modification
  other properties ....
}

But looks like you missed that train in existing event schema (with no versioning). So now you would need some dirty workaround for at least sometime initially. But never too late to introduce versioning. To start with, your event would look like below. Note I have introduced version property so that any new subscriber is aware of that from now on, whereas your existing subscribers won't be broken at the same time since no existing event properties have changed. Meanwhile, you can notify those old subscribers to transition to the newer. In future, such change would be easier since now you have versioning.

{
  version : 2,
  orderid : 123455,
  customerid : [email protected], // for V1 compatibility
  // name new customerid field something different, below is just for example
  customerid_v2 : 5435gd98, // V2
  other properties ....
}

Or it can be like (moved customer details inside a nested json):

{
  version : 2,
  orderid : 123455,
  customerid : [email protected], // for V1 compatibility
  customer : { 
    id : 5435gd98,
    email : [email protected]
  }
  other properties ....
}