Add status to Get webhook subscription/subscriptions

[kkuo]

A status indicating the TMS's ability to use the webhook that the client registered at the TMS might be helpful if one was available in the spec. The client could then check the status/health of the webhook and choose to defer to a polling mechanism until the issue has been resolved.

Currently the expectation is that the TMS would stop sending events to any unhealthy webhooks? But there is no way for the client to know why the TMS stopped sending events. It could be because the TMS<>Client don't ship a lot of loads so naturally there aren't a lot of events. It could be something the client did like auth keys expired or rotated at the client. It could be a while before this outage is noticed by the client.

The TMS shouldn't delete any webhooks registered by the client if it starts misbehaving since that'll be very confusing and jarring. It would also force the clients to have an internal table to record all the endpoints that have been registered at all TMSs and use the presence/absence of the webhook to indicate if the webhook was deleted by the TMS. This seems to be extra burden by the client because the TMS already has this record so the client shouldn't need to keep its own records.

The assumption is that TMS would use an email, page, other out-of-spec communication mechanism to the registered clients when webhook goes down. There are a lot of issues with emails and seems like a webhook lifecycle definition isn't complete and relying on manual processes to get operations back running. This seems to be against trying to have an API so we can automate.

For critical flows like appointment change notifications we don't have good acceptance criteria for that flow if the TMS is having issues with sending events. I'm not sure how to define certification in the absence of a status.

The proposal is to add an optional status object in the subscription object. The status object can have multiple fields like lastSuccessfulSendTime, currentHealth, etc. Exact field names TBD.

@GranataJBH @dutabado @miller79

[kkuo]

@miller79 a diagram hopefully helps with illustration the problem a bit better.

[kkuo]

Meeting 9/6
Decided to not add a status

• Too late, spec is sort of locked down
• Compliance is the same regardless of modification to the spec, so if TMS and carriers want it, the TMS is free to add it without any penalty to their scoring/badging.
• TBD adding to the documentation recommendations for both the TMS and carriers on their implementation (TMS does not return subscriptions that are having errors; carriers must store and maintain their own list to compare against TMS's list)