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.)

You need
Global Admin (global webhooks) or Team Manager (team and service webhooks)
Where
Webhook in the SQIBS menu
Result
Other tools hear about incidents at once

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.