Overview
An outgoing webhook sends an HTTP request to another tool when something happens in SQIBS: an incident opens, is acknowledged or resolved, or an SLA is breached. Use it to update a ticket system, post to chat, or start your own automation. (To receive alerts, use the API integration instead.)
Scope
| Scope | Fires for events in |
|---|---|
| Global | Every team. |
| Team | That team. |
| Service | That service. |
Choose it in Webhook related with. If several webhooks cover the same event, each one fires.
Create a webhook
Click Add Webhook and fill in:
| Field | What to enter |
|---|---|
| Name*, Description | A unique name, and what it is for. |
| Events* | Any of: Incident created, Incident acknowledged, Incident unacknowledged, Incident resolved, Incident Response Threshold, Incident MTTR breached, Incident MTTA breached, SLA Breached, SLA Breach Reminder. |
| URL*, HTTP Method | The receiving URL, and GET, POST, PUT or DELETE. |
| Authorization Type* | None, Basic (user name and password; SQIBS encodes them), API Key (a name and value, sent as a header or a URL parameter) or Bearer Token. |
| Headers | Extra headers, up to 20. |
| HMAC Signing | Sign the body with HMAC-SHA512 (below). Request body only. |
| Send data using* | Request Body (a payload you write) or Query Parameters. |
| Retry Count*, Retry Interval* | Retry a failed call 0 to 4 times, 1 to 5 minutes apart. |
| Failure Notification Email | Who to tell if the webhook keeps failing. |
Click Test to send a test call and see the Response Code, then Save. Use Deactivate to pause a webhook without deleting it.
Placeholders
Type {{ in the payload or a parameter value to pick a placeholder. SQIBS replaces it when it sends:
| Placeholder | Value |
|---|---|
{{incident.id}} |
Incident id |
{{incident.title}} |
Title |
{{incident.description}} |
Description |
{{incident.urgency}} |
high or low |
{{incident.status}} |
triggered, acknowledged or resolved |
{{incident.mapped_with}} |
The value the incident was mapped with when it opened |
{{incident.url}} |
Link to the incident |
{{webhook.id}} |
Webhook id |
{{webhook.event}} |
The event, for example incident.created |
{{user}} |
The user behind the event |
{{timestamp}} |
When it was sent, yyyy-MM-ddTHH:mmZ |
Custom logic
Map SQIBS values to the receiver's values with if(...) return(...); inside triple braces. Use at least one if and exactly one plain return, which acts as the default. if works with incident.urgency, incident.status and webhook.event.
{
"id": "{{incident.id}}",
"title": "{{incident.title}}",
"status": "{{incident.status}}",
"link": "{{incident.url}}",
"severity": {{{ if(incident.urgency==high) return("P1"); if(incident.urgency==low) return("P3"); return("P4"); }}}
}
This sends, for example, "severity": "P1" for a high-urgency incident. After replacement the body may be up to 20000 characters, query parameters up to 10000.
Verify the HMAC signature
The header you name carries timestamp,signature. The signature is HMAC-SHA512, with the HMAC Key from SQIBS, of timestamp + "." + body. In Python:
import hmac, hashlib, time
def verify(header_value: str, body: bytes, key: str, max_age=300) -> bool:
timestamp, signature = header_value.split(",", 1)
if abs(time.time() - int(timestamp)) > max_age: # reject old or replayed calls
return False
data = timestamp.encode() + b"." + body
expected = hmac.new(key.encode(), data, hashlib.sha512).hexdigest()
return hmac.compare_digest(expected, signature)
Use Regenerate key if the key leaks; update the receiver at the same time.