Document upcoming changes to webhooks payloads

[fkorotkov]

These are proposed new fields that will come to the payloads and GraphQL API in the coming weeks.

These events will allow to improve export of the events into systems like Datadog. See the following issue:

• Respect timestamp of the event upon insert cirrus-webhooks-server#8
• Enrich events with more tags  cirrus-webhooks-server#9

[edigaryev]

This needs a timestamp field for build's and task's, similarly to audit_event's.

Currently, for build's we only emit a single timestamp, which is build.changeTimestamp, but it doesn't change when the build gets updated.

For tasks we could use the statusTimestamp, but it would be nice to have a uniform timestamp field to avoid ambiguity for the webhook receiver implementors.

[fkorotkov]

@edigaryev what do you think about a request header. Since the payload is a GraphQL query response and I don't think we can add timestamp there. 🤔

[edigaryev]

@edigaryev what do you think about a request header. Since the payload is a GraphQL query response and I don't think we can add timestamp there. 🤔

That would totally work too.

[edigaryev]

Since the payload is a GraphQL query response and I don't think we can add timestamp there. 🤔

On a side note, it seems that the action and old_status fields are merged somehow, so probably we can:

[edigaryev]

Also, perhaps we should make the audit_event to conform to this format, or vice versa, because currently it differs, see screenshot below.

Note that the body is not a nested object, but instead a JSON string: