Outbound Webhooks
Outbound webhooks communicate events in SIGNL4 to 3rd party applications
This page describes the JSON format of the notifications that are sent as HTTP POST to your web-hook.
You can register your web-hooks in the account management of SIGNL4 here. Please note that you cannot register the inbound web-hook from your SIGNL4 team as an outbound web-hook for event notifications in order to prevent infinite data loops.
Each notification contains a unique identifier as value of the id property. You may use it to ensure that you process notifications only once in case they are received multiple times by your web-hook. Moreover, each notification contains one or more objects for which the notification was triggered (e.g. a user object when a user has punched-in). You may query additional properties of these objects via the SIGNL4 API by using their id value.
We strongly recommend to utilize the X-S4-ExternalID parameter to match outbound webhook calls with the original inbound webhook call you used to submit an event to SIGNL4. Here is a video on how to parameter can be used for 2-way synching.
New Signl Created
Signl Confirmed
Signl Resolved
Signl Escalated
Signl Annotated
Duty Period Started
Duty Period Ended
Somebody Punched-In
Somebody Punched-Out
New Signl Created
The eventType value of 200 means that a new Signl was created for your team.
Some details are passed within the alert object.
You can use the eventId attribute to correlate this notification to a Signl that you have triggered earlier via the inbound webhook of your team (the inbound webhook returns an eventId for each submitted event.).
If you prefer correlation by an ID in your external system you can pass that value in a parameter named X-S4-ExternalID and you will get it back in the externalEventId property of the alert object.
{ "eventType": 200, "eventRaisedUtc": "2017-09-01T08:11:37.4815663Z", "subscription": { "id": "0acf8014-22f2-4503-88d7-f7d05b46744f" }, "alert": { "statusCode": 1, "eventId": "2518783235949759942_fbc7b4a4-badd-47b8-9e1d-702fb6a1a0b2", "externalEventId":"Content you passed in the X-S4-ExternalID parameter" "id": "2518981069381242800_2ab1b5e0-f1b7-4c3e-9adf-6c157eeb4685" }, "id": "dd209a2d-e037-41ee-b37d-f605cc0a39fb"}Signl Confirmed
The eventType value of 201 means that the status of a Signl in your team has changed.
If the statusCode value of the alert object equals 2, it means that the someone (see user object) has confirmed the Signl.
Some more details will be passed within the alert object.
You can use the eventId attribute to correlate this notification to a Signl that you have triggered earlier via the inbound webhook of your team (the inbound webhook returns an eventId for each submitted event).
If you prefer correlation by an ID in your external system you can pass that value in a parameter named X-S4-ExternalID and you will get it back in the externalEventId property of the alert object.
{ "eventType": 201, "eventRaisedUtc": "2017-09-01T08:11:37.4815663Z", "subscription": { "id": "0acf8014-22f2-4503-88d7-f7d05b46744f" }, "user": { "username": "Rene", "mailaddress": "rene@signl4.com", "id": "f0bd5063-9588-51cf-b3d9-94e5647dedc5" }, "alert": { "statusCode": 2, "eventId": "2518783235949759942_fbc7b4a4-badd-47b8-9e1d-702fb6a1a0b2", "externalEventId":"Content you passed in the X-S4-ExternalID parameter", "acknowledgedUserIds": [ "f0bd5063-9588-51cf-b3d9-94e5647dedc5" ], "id": "2518981069381242800_2ab1b5e0-f1b7-4c3e-9adf-6c157eeb4685" }, "id": "dd209a2d-e037-41ee-b37d-f605cc0a39fb"}Signl Resolved
The eventType value of 201 means that the status of a Signl in your team has changed.
If the statusCode value of the alert object equals 4, it means the Signl was resolved.
The user object holds further information about the person who has resolved the Signl.
Some more details are passed within the alert object.
You can use the eventId attribute to correlate this notification to a Signl that you have triggered earlier via the inbound webhook of your team (the inbound webhook returns an eventId for each submitted event).
If you prefer correlation by an ID in your external system you can pass that value in a parameter named X-S4-ExternalID and you will get it back in the externalEventId property of the alert object.
{ "eventType": 201, "eventRaisedUtc": "2017-09-01T08:11:37.4815663Z", "subscription": { "id": "0acf8014-22f2-4503-88d7-f7d05b46744f" }, "user": { "username": "Rene", "mailaddress": "rene@signl4.com", "id": "f0bd5063-9588-51cf-b3d9-94e5647dedc5" }, "alert": { "statusCode": 4, "eventId": "2518783235949759942_fbc7b4a4-badd-47b8-9e1d-702fb6a1a0b2", "externalEventId":"Content you passed in the X-S4-ExternalID parameter" "acknowledgedUserIds": [ "f0bd5063-9588-51cf-b3d9-94e5647dedc5" ], "id": "2518981069381242800_2ab1b5e0-f1b7-4c3e-9adf-6c157eeb4685" }, "id": "dd209a2d-e037-41ee-b37d-f605cc0a39fb"}Signl Escalated
The eventType value of 202 means that a Signl was not confirmed in time and was therefore escalated to a manager.
Some more details are passed within the alert object.
You can use the eventId attribute to correlate this notification to a Signl that you have triggered earlier via the inbound webhook of your team (the inbound webhook returns an eventId for each submitted event).
If you prefer correlation by an ID in your external system you can pass that value in a parameter named X-S4-ExternalID and you will get it back in the externalEventId property of the alert object.
{ "eventType": 202, "eventRaisedUtc": "2020-01-10T12:27:19Z", "subscription": { "id": "b8fdd850-e2ad-45ff-924d-9c332a063200" }, "team": { "id": "0e8979f7-0c6a-472d-8918-ecfd339252f8" }, "alert": { "statusCode": 1, "eventId": "2518236416806594587_0e67b746-6c88-4ddf-8872-99690b0457d9", "externalEventId": "INC091210", "acknowledgedUserIds": [], "id": "2518236416804564453_12ea0f6f-948c-43d0-9034-f9565d7b6bd2" }, "id": "27283793-47c8-4da2-9767-d37be224338d"}Signl Annotated
The eventType value of 203 means that someone from your team has annotated a Signl.
The annotation object contains the message. The user object holds the id of the user in your team who did the annotation. You can use the REST API to get more data from that user by the id
Some more details of the Signl will be passed within the alert object.
You can use the eventId attribute to correlate this notification to a Signl that you have triggered earlier via the inbound webhook of your team (the inbound webhook returns an eventId for each submitted event).
If you prefer correlation by an ID in your external system you can pass that value in a parameter named X-S4-ExternalID and you will get it back in the externalEventId property of the alert object.
{ "eventType": 203, "eventRaisedUtc": "2018-04-17T15:00:32Z", "subscription": { "id": "1578ebd9-0a27-44ab-bc8e-52cd7d32e81d" }, "user": { "username": "Rene", "mailaddress": "rene@signl4.com", "id": "f0bd5063-9588-51cf-b3d9-94e5647dedc5" }, "alert": { "statusCode": 0, "eventId": "2518783235949759942_fbc7b4a4-badd-47b8-9e1d-702fb6a1a0b2", "externalEventId":"Content you passed in the X-S4-ExternalID parameter", "id": "2518783235958846071_4e2dfab2-4717-42bc-8d37-8682402309c2" }, "annotation": { "message": "OK, I'll take care about it.", "id": "2518783235661483318_99ebffe0-1b90-40ef-990a-fbd842484761" }, "id": "141c0f88-7831-4d5e-b055-f6e83c269770"}Duty Period Started
When you have activated the SIGNL4 duty assistant (e.g. in the account management of SIGNL4 here), your web-hook will receive this notification when your team starts duty (indicated by an eventType value of 300). The team object relates to your SIGNL4 team.
{ "eventType": 300, "eventRaisedUtc": "2017-09-01T09:16:17.3717355Z", "team": { "id": "f1801955-4724-44de-902a-f6f02ba9e10f" }, "id": "f56a6b59-1197-4e7d-8eca-8d21a4b57ec3"}Duty Period Ended
When you have activated the SIGNL4 duty assistant (e.g. in the account management of SIGNL4 here), your web-hook will receive this notification when your team has finished duty (indicated by an eventType value of 301). The team object relates to your SIGNL4 team.
{ "eventType": 301, "eventRaisedUtc": "2017-09-01T09:16:17.3717355Z", "team": { "id": "f1801955-4724-44de-902a-f6f02ba9e10f" }, "id": "f56a6b59-1197-4e7d-8eca-8d21a4b57ec3"}Somebody Punched-In
The eventType value of 302 means that somebody in your team has punched-in. The team object relates to your SIGNL4 team. The user object relates to user who has punched-in.
{ "eventType": 302, "eventRaisedUtc": "2017-09-01T09:16:17.3717355Z", "team": { "id": "f1801955-4724-44de-902a-f6f02ba9e10f" }, "user": { "id": "e31da15f-7e13-43f1-b4a5-1ce3b470a504" }, "id": "f56a6b59-1197-4e7d-8eca-8d21a4b57ec3"}Somebody Punched-Out
The eventType value of 303 means that somebody in your team has punched-out. The team object relates to your SIGNL4 team. The user object relates to user who has punched-out.
{ "eventType": 303, "eventRaisedUtc": "2017-09-01T09:16:17.3717355Z", "team": { "id": "f1801955-4724-44de-902a-f6f02ba9e10f" }, "user": { "id": "e31da15f-7e13-43f1-b4a5-1ce3b470a504" }, "id": "f56a6b59-1197-4e7d-8eca-8d21a4b57ec3"}
