About webhooks

A webhook is an HTTP-based callback function that allows event-driven communication between web applications. To implement webhooks in Helix ALM you need to:

  • Configure the webhook recipient, which is the destination endpoint for a webhook notification. The webhook recipient is used in the webhook rule. See Configuring webhook recipients.
  • Configure the webhook rule, which contains all the details required to generate webhook notifications when an issue, test case, test run, requirement, or requirement document is added or changed in Helix ALM. To configure a webhook rule, you need to have defined at least one webhook recipient. See Configuring webhook rules.

  • In addition to configuring webhooks in Helix ALM, you must also create an HTTPS service that listens for webhook notifications.

JSON information

A webhook notification is the delivery portion of a webhook. It involves sending a prepared JSON payload to a specified URL via an HTTP POST request.

The Helix ALM JSON payload for webhooks includes the following:

{
   "version": 1, 
   "projectID": "Traditional Template",
   "events": [ 
   { 
      "action": "changed", 
      "condition": ["linkAdded" "changed event"], 
      "id": 1, // Webhook rule id  
      "name": "WebHook Trigger Name", 
      "created": "2013-06-05T18:29:16Z", 
      "item": { 
         "itemType": "issue", 
         "requirementType": { // for itemType == "requirement" 
            "id": 2, 
            "label": "Feature"}, 
         "id": 135, 
         "number": 3205, 
         "tag": "IS-3205"   
      } 
   }] 
}

Header information

Helix ALM uses custom headers as part of the webhook notification. These are included in every notification. Please keep in mind that these headers are reserved and may not be used as a name for a custom header.

Header Description
Content-Type Defines how Helix ALM is sending the content. Set to Content-Type: "application/json; charset=utf-8".
X-HALM-WebHook-Version Contains the version number of the webhook. Used by the recipient to direct the webhook notification to the proper handler.
X-HALM-WebHook-ID Contains the webhook's unique identifier. Typically this is a UUID, unless you are testing the connection, in which case the ID is set to ping. This header is processed before the JSON data to validate the request and prevent replay attacks.
X-HALM-WebHook-Timestamp Contains the timestamp of the webhook. This header is processed before the JSON data to validate the request and prevent replay attacks.
X-HALM-WebHook-Signature-Primary Contains the primary signature used to validate the contents of the request. You define the primary signature when you configure the webhook recipient. See Adding webhook recipients
X-HALM-WebHook-Signature-Secondary Contains the secondary signature, if one exists, used to validate the contents of the request. The secondary signature is a temporary signature that Helix ALM generates when you change the primary signature. See Changing webhook signatures
X-HALM-WebHook-Retry Contains a retry number. This header is only included if a webhook fails and Helix ALM is retrying it. This is provided so that the recipient can detect that a failure had occurred.

Generating a webhook notification

Helix ALM generates a webhook notification when the item being changed passes the webhook rule filter in the following cases.

Condition Description
Core items are added A webhook is sent for each item added (manual add, XML import, REST API, and so forth).
Core items are edited A webhook is sent for each item changed.
Core items are deleted A webhook is sent for each item deleted.
Core items are numbered A webhook is sent for each item numbered.
Core items are renumbered A webhook is sent for each item renumbered.
Defects are merged A webhook is sent for each of the following:
  • Defect the other defects merged into.
  • Each defect that was deleted due to the merge.
Core items are changed when escalation rules run A webhook is sent for each item changed by the escalation rules.
A test case is created from a defect A webhook is sent for the new test case.
Test cases are generated from requirements A webhook is sent for each test case generated.
Test runs are generated from test cases A webhook is sent for each of the following:
  • Parent test case that generates the test runs.
  • Each test run generated.
A document has requirements added or removed (manually, XML Import, REST API, etc.) A webhook is sent for each of the following:
  • Document that was changed.
  • Each requirement added or removed.
When requirements are moved in the document tree A webhook is sent for each of the following:
  • Document that was moved.
  • Each requirement manually moved.
When test cases are created from automation results A webhook is sent for each test case created
When linked items are made suspect or unsuspect A webhook is sent for each of the following:
  • A webhook for each item made suspect or unsuspect
  • If the suspect action was in a document
  • A webhook will be sent for the document
  • A webhook will be sent for the parent requirement for the items made suspect
When items are added or removed from a link A webhook will be made for each item added to or removed from a link

Webhooks are NOT sent when:

  • A tracked email is sent or received.

  • When a requirement is automatically moved in a tree. Webhooks are only sent when a requirement is manually moved.

Handling failed attempts

If sending a webhook notification to a recipient fails, Helix ALM Server attempts to resend the notification up to five times before disabling the webhook. Helix ALM uses the following wait times between attempts:

  • First attempt - 5 minute wait (5 minutes total)
  • Second attempt - 10 minute wait (15 minutes total)
  • Third attempt - 30 minute wait (45 minutes total)
  • Fourth attempt - 120 minute wait (165 minutes total)
  • Fifth attempt - 600 minute wait (765 minutes total)

The total time it takes before Helix ALM disables the webhook recipient due to repeated failures is 12.75 hours.