Webhooks: Create and test your first Webhook

Document ID : KB000091762
Last Modified Date : 17/04/2018
Show Technical Document Details
Introduction:
Webhooks allow you to create rules in CA Agile Central that send information to an external server when the rule triggers. Only subscription administrators can manage webhooks.

This doc will walk you step-by-step and help you create and test your first Webhook.

Our sample Webhook will trigger for any Defect whose ScheduleState be set to Completed. To test the Webhook functionality we will use a free website https://webhook.site . This site will let you generate a unique URL which we shall set as the TargetURL for our Webhook. This site will then capture incoming requests and allow examining the full JSON arriving payload.

There are many other similar websites you can use for developing and testing your Webhooks.
Background:
You can learn more on Webhooks at: 
https://help.rallydev.com/manage-webhooks

A complete Webhook technical API guide can be found at: 
https://rally1.rallydev.com/apps/pigeon/docs/webhooks
Instructions:
Creating a Webhook requires an http POST command carrying the Webhook's definition. This will get registered in Rally.
We are using PostMan to make that POST.

Screen 1 shows the full URL we post to, also take note we use API Keys to authenticate and authorize this post to Rally.
User-added image

Screen 2 is showing our post's Body which is the JSON formatted definition of the Webhook.
As you see our TargetURL is the unique URL we generated at the free Webhook site as explained earlier.
Lines 6-12 are the contents of the Webhook, they register a trigger for any Defect that will have their ScheduleState be 'Completed'.
User-added image

We click "Send" to submit this post to Rally. Let's check the response.
We see on the right a "200 OK" response (not displayed in the screenshot below).
Scree 3 is showing the Webhook's registration details. You can see the subscription, the type, the creation date, the object type and the expressions details among other details. Specifically, see line 21 (Disabled = false) which serves as receipt that our Webhook is on and ready for use.

User-added image

Now, let's go into Rally and find our Webhook. Screen 4-6 show that we find the Webhook and that it's enabled.

User-added image

User-added image
User-added image


We are ready to test our Webhook. We created a Defect called: "A Test Defect", We will now edit it and change its ScheduleState to be 'Completed' - see screens 7-8:

User-added image
User-added image

In order to learn if our Webhook triggered we shall examine our unique URL in our test site , which was the target of our Webhook. 
Screen 9 shows a post message was received at our page:

User-added image

Screens 10-11 show the details of that incoming post. That page can show the Payload contents in JSON , we will go over the details and confirm it's sourced by our defect (see 'A Test Defect' in screen 11).
User-added image

User-added image

At this point our Webhook is registered and working.