A webhook is an interesting creature. Many people are familiar with the idea of requesting information from a RESTful API interface, but that's still a "pull" concept. What if the information came to you automatically? This is the idea behind a webhook.
Years ago, we were promised push technologies that fed us information that was relevant to us. While we have services that feed us information, many of these services are still very much pull based technologies that mimic push technology. Now, with the advent of serverless computing, "if this then that" workflow processes and devops automation, we're really starting to see true push technologies coming into their own.
Wehooks are a major part of this silent revolution and Agile Central supports webhooks.
The bad news is, the "last mile" is missing. We can send webhooks, but there aren't many partners that are available to do anything with them. Part of the difficulty is that the payload that is sent in a webhook isn't standard across the board. You can't just simply look for a "message" parameter in a webhook and expect it to be there every time. Every vendor is free to layout their payload in any way they see fit. The Agile Central webhooks are very rich with detail.
There's no way I can fit an entire Agile Central webhook message in this post, but a sample of the information contained looks like this:
{
"message": {
...
"object_type": "Defect",
"transaction": {
...
"user": {
"uuid": "ae784947-d29d-4cf4-8ed0-e64ab75487eb",
"username": "REDACTED@rallydev.com",
"email": "REDACTED@ca.com"
},
...
},
"state": {
"55c5512a-1518-4944-8597-3eb91875e8d1": {
"value": "DE1",
"type": "String",
"name": "FormattedID",
"display_name": "Formatted ID",
"ref": null
},
...
},
...
"subscription_id": 209,
...
"changes": {
...
"7f25a8ae-6948-49a9-92f5-b437ca213251": {
"value": {
"value": 32.0,
"units": "Points"
},
"old_value": {
"value": 16.0,
"units": "Points"
},
..."display_name": "Plan Estimate",
"ref": null
}
},
"action": "Updated"
},
...
}
This is only a handful of the 800 lines that the original message contains. A lot of the other information contained in the payload would be current state of all fields, details around the artifact type, object IDs, etc. A sample payload can be seen here.
The trigger for these is based on a variety of configurable parameters. For example, I have a webhook that always fires when DE1 is updated. This gives me a predictable way to trigger a webhook. For some, they may want a webhook that triggers any time a change is made to a User Story that is In-Progress or Defects that are in a particular project.
These payloads then get delivered to a listening destination that has some code capable of parsing the JSON request contained in the body and then acting upon that code.
In the next post, we'll go over how to create a webhook.