Registering a webhook

On this page

Navigate to Webhook Configuration

Click "Webhook Configuration" under the Admin section.

Flow Diagram

Configure the Webhook

As there is no webhook registered , No Records found is displayed
To configure the webhook, click Add button on the top right corner.

Enter the details of the webhook

Webhook Name: Input a name for the webhook, which needs to be configured.
Select Tool: Input the tool name whose webhook needs to be configured.
Is Event Processing : Toggle this flag if webhook is used for event processing.
Label Name: This label name will be auto populated as soon as the user selects the tool. It should follow the nomenclature of ToolCategory:LabelName:DATA. ( Populated label name won't be editable in case of event processing and label is formed as WEBHOOKNAME_TOOLNAME_EVENT)
Data Format: The data format which is supported, is JSON.
MQ Channel : This field gets auto populated as soon as the webhook name is entered with a prefix “IPW_”
Dynamic Template : This field is an alternate option of Response template .It has to be a valid JSON.
Response Template: The response template has to be added should be in string format.
Event Config Details : Event config json object has to be added if webhook is used for event processing.

Please refer webhook event processing configuration section for detailed configuration information if wekhook to be used for event processing.

Sample Response Template:

repository.name=reponame,

head_commit.id=commitId,

head_commit.message=message,

head_commit.timestamp=commitTime,

head_commit.author.name=authorName

For the response of the webhook data, please check Annexure 1.

Node Updation :- If the Neo4j node has to be updated ,based on the unique key, set the flag true and enter the required unique property. (This is disabled in case of event processing)

Insights TimeX : This has three fields namely -
- Time Field : This has to be last value from key-pair of response template.
- Epoch Time : If the time field is in epoch format mark the toggle as true.
- Time Format : If the time field is not in epoch format, then time format has to be given.

Sample Time Format -Time 1. 2020-03-02T05:48:48Z (yyyy-MM-dd'T'HH:mm:ss'Z')

2. 2019-06-27T14:19:55+05:30 (yyyy-MM-dd'T'HH:mm:ssXXX)

3. 2019-06-27T14:19:55-05:30 (yyyy-MM-dd'T'HH:mm:ssXXX)

4. 2019-11-13 14:35:17 UTC (yyyy-MM-dd HH:mm:ss)

5. 2019-07-03T10:39:22+0000 (yyyy-MM-dd'T'HH:mm:ssZ)

For More formatter check https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html

Add Time Fields : This is optional field, in case you want to add more time fields and time format. The time fields included are by default not in epoch, so time format needs to be mentioned.
Data Enrichment : This includes-
- Source property
- Key pattern
- Target property

Note: To use Derived Configuration (Insights Timex, Time Fields, Data Enrichment), please delete webhook created before 13/03/2020, and configure new.

toolDetail.json file which contains the list of tools along with their labels needs to be added under INSIGHTS_HOME.
Labels are auto-populated once the Tool is selected
Label name should follow the nomenclature of TOOL_CATEGORY:LABEL_NAME:DATA.(If webhook is not used for event processing)
User can enter either Response template or Dynamic Template ,but one is mandatory.

Webhook event processing configuration :

Response Template : Response template must contain webhook event name as mandatory property and property name must be "webhookEvent"
Event Config Details: Json Object which has to follow below structure .

{
"config":[
{
"event":"jira:issue_deleted",
"query":[
"match(n:ALM:JIRA_AGENT:DATA) where n.key='{jiraKey}' set n.isDeleted =true return n "
]
},
{
"event":"jira:issue_updated",
"query":[
"match(n:ALM:JIRA_AGENT:DATA) where n.key={jiraKey} set n.isDeleted =true return n"
]
}
]
}

in above config json property names "config" , "event" , "query" must be with the same name .

event property : Event property indicates for which webhook event the respective queries to be executed which are defined in query array .

query property : Query property is json array which takes multiple queries to be executed in order when webhook event matches to event property name.

Defined query takes dyanamic data with string substitution as {}

The keys defined in the response template combined with dyanamic template are available to use as string substitution.

suppose response template is defined as :

sprint.name=sprintName,
sprint.id=sprintId,
sprint.originBoardId=boardId,
webhookEvent=webhookEvent,
issue.key=jiraKey

all above keys like sprintName , sprintId , boardId, webhookEvent , jiraKey are available to be used in query as string substitution like "match(n:ALM:JIRA_AGENT:DATA) where n.key= {jiraKey} set n.isDeleted =true return n" , here {jiraKey} key jiraKey is used from response template and value of the key is replaced dynamically.

If value of the key is string then make sure that you use single quote like '{sprintName}' and if it is integer value then without single quote like {jiraKey}

Once webhook is configured and subscribed then any webhook event matches event name defined in event config then webhook engine run queries on the fly . If queries run successfully then MQ message is acknowledged .
If queries have any syntax errors as well as if queries are failed due to data is not present on which query is being executed in such cases event are stored on the label defined while configuring webhook and those events will further be processed by webhook offline event processor.
Offline event processor retries missed events for the time window defined in server-config property as "eventProcessingWindowInMin":60 , if window time is elapsed then event is discarded.

If webhook event does not match up with event defined in event config json then MQ message is acknowledged and event is discarded.

Configuring webhook offline processor :

Manage Webhook event processing through Schedule Task Management , Task name is WebhookOfflineEventProcessing