The SIGNL4 webhook can do more than just receive events to trigger Signls. For example, it can also update previously triggered Signls (status change) to keeps both systems in sync. Notified users can then immediately see if an incident in the third party system has already been resolved again.
Furthermore, it is also possible to add additional incident properties/content or to control how the team is to be notified.
Overview of control parameters
Control parameters have a dedicated pre-defined name and can be included anywhere in the submitted event payload (e.g. JSON). The following table displays an overview of all available control parameters.
| Parameter | Type of control | Description |
| X-S4-Service | Incident data and routing | Assigns the triggered Signl to the category have the name of this parameter value. SIGNL4 categories can augment the incident or define who is responsible, etc. Will be overwritten if category is assigned in distribution rule. |
| X-S4-Location | Incident data | Used to define where the incident is located. Value is a string containing latitude and longitude separated by a coma. |
| X-S4-AlertingScenario | Alerting workflow | Possible values include “single_ack” (acknowledgement from only one person on duty is required) and “multi_ack” (acknowledgement from all people on duty is required). If “emergency” is specified, the triggered Signl gets assigned to the emergency category and always all people in the team are notified (regardless of their duty status). |
| X-S4-Filtering | Event filtering | A bool value of true or false to apply event filtering for this event, or not. If set to true, the event will only trigger a Signl if it matches the setup keyword filtering in a Signl category of the target team (i.e. it is whitelisted or not blacklisted). Otherwise it may trigger a Signl assigned to the Default category, in case no specific category keyword setup matches. |
| X-S4-ExternalID | Status mapping | Used to correlate multiple events sent to the webhook to one and the same incident. Type is string and value should be a unique incident id. |
| X-S4-Status | Status mapping | Used to update created incidents (Signls) based on the incident ID (X-S4-ExternalID). Value represents the name of the status the corresponding Signl should transition to. Possible values are “New”, “Acknowledged”, “Resolved”. |
Status mapping
To update the status of a previously triggered signal, it is first necessary to specify a unique incident ID (X-S4 ExternalID) when transmitting the initial incident. This ID must be the same for subsequent events that are then only to change the status.
The new status, which a previously created Signl should get assigned, is specified with the parameter "X-S4-Status". The following is an example of the process:
1 - Initial incident event which triggers a signal
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-ExternalID": "e3b0c44",
"X-S4-Status": "New"
}X-S4-Status is optional when initially triggering the Signl.
2 - Incident is confirmed in the third party system, Signl is to be acknowledged
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-ExternalID": "e3b0c44",
"X-S4-Status": "Acknowledged"
}When the status of a previously created Signl should be updated, all non-control parameters or JSON objects are optional.
3 - Incident is closed in the third system, Signl is to be closed
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-ExternalID": "e3b0c44",
"X-S4-Status": "Resolved"
}When the status of a previously created Signl should be updated, all non-control parameters or JSON objects are optional.
Status mapping via URL query parameters
The status mapping described above presumes that you have control over the event payload / body in the 3rd party system to inject the SIGNL4 control parameters. If this is not the case and you must work with a predefined schema, you can instruct the mapping via the below listed URL query parameters. They instruct which parameters in the body hold values required for the previously described status mapping mechanism.
| Query parameter | Description |
| ExtIdParam | Name of the parameter in the posted event body that holds a unique incident id required for status mapping (equivalent for ‘X-S4-ExternalID’) |
| ExtStatusParam | Name of the parameter in the posted event body that holds a status which is mapped to the SIGNL4 status of “New”, “Acknowledged” or “Closed”. |
| NewStatus | Value that the body parameter which name equals the value of “ExtStatusParam” must have, to trigger a new Signl. If any other status value than behind “NewStatus”, “AckStatus” or “ResolvedStatus” is received, the event is discarded. |
| AckStatus | Value that the body parameter which name equals the value of “ExtStatusParam” must have, to transition the corresponding Signl’s status to acknowledged. |
| ResolvedStatus | Value that the body parameter which name equals the value of “ExtStatusParam” must have, to transition the corresponding Signl’s status to closed. |
The same status mapping flow using URL query parameters to describe the control parameters looks as follows:
1 - Initial incident event which triggers a signal
POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"Id": "e3b0c44",
"Status_t": "DOWN"
}2 - Incident is confirmed in the third party system, Signl is to be acknowledged
POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"Id": "e3b0c44",
"Status_t": "PENDING"
}3 - Incident is closed in the third system, Signl is to be closed
POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"Id": "e3b0c44",
"Status_t": "UP"
}Discarded in-between events
Nothing would happen and especially no new Signl would be triggered when the 3rd party system would initiate "in-between" update events like the one below and these two conditions are met:
- all three status (new, acknowledged and closed) are declared/mapped in the query parameters
- each event still contains the same external id in the declared/mapped body parameter
POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"Id": "e3b0c44",
"Status_t": "IDENTIFIED"
}Assigning a specific category
If you want to assign a specific incident category from the 3rd party system, you may include the “X-S4-Service” parameter when sending a new incident event. It needs to contain the name of a category in the team that the Signl will be created for. It can be combined with any other control parameters.
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-ExternalID": "e3b0c44",
"X-S4-Status": "New",
"X-S4-Service": "Database"
}Sending geo location
It is also possible to submit a geo location when triggering new Signls. Notified staff can then e.g. see where the incident has occurred (map in Signl details) and can quickly find out how to get there. To submit location information, use the control parameter “X-S4-Location” and pass latitude and longitude separated by a coma as string value:
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-ExternalID": "e3b0c44",
"X-S4-Status": "New",
"X-S4-Service": "Database",
"X-S4-Location": "52.4354955,13.0540154"
}Strict keyword filtering
SIGNL4 categories can be used to filter out the noise or apply some classification to the incoming event. They each contain an include and an exclude list of keywords which are searched in the event you send to e.g. the webhook. If the event contains words which are on the exclude list (block list) the corresponding category is not assigned to the event you sent in. If it on the other hand contains words which are in the include list (allow list) the category is assigned. If at the end no category is assigned to the event, it can be entirely filtered and no Signl would be created. As a result no one would be notified at all. This behavior can be enabled when you include X-S4-Filtering with a value of true. If false or not present, a Signl will be created and assigned to the default category when there is no better category match.
{
"Title": "Critical production failure",
"Message": "Check line machine C immediately",
"Severity": "High",
"Business Details": {
"Impact": "Major",
"Scope": "Unlimited"
},
"X-S4-Filtering": true
}
Comments
0 comments
Please sign in to leave a comment.