Incident Webhook Push¶

Webhook is used to push key changes of incidents to third-party systems. You can integrate incident information into ITSM, automation platforms, or internal business systems, allowing third parties to continue creating tickets, synchronizing statuses, or triggering automated processes based on the received data.

Webhooks can be created and managed in Incident Center > Configuration Management > Webhook.

Prerequisites¶

First, prepare a third-party address that can receive POST requests. Webhook supports HTTP and HTTPS addresses; HTTPS is recommended for production environments. For security reasons, intranet, loopback, or local addresses cannot be configured.

Configure Webhook¶

1. Click Create Webhook on the Webhook page;
2. Fill in the name and third-party receiving URL;
3. Select the incident events to push: | Event | Description | | --- | --- | | Incident Created | Pushed when a new incident is created. | | Status Changed | Pushed when the incident status changes. | | Level Changed | Pushed when the incident level changes. | | Assignee Changed | Pushed when the incident assignee changes. | | Aggregation Changed | Pushed when the aggregated incident's associated events change. Only effective for incidents generated by incident aggregation rules. |
4. Click Generate Token. The Token is only generated by the Guance platform. Copy it immediately and securely save it in the key configuration of the third-party receiving service;
5. Set the enabled status and save.

Test Send¶

After saving the Webhook, click Test in the Webhook's operations and select the event type. The system will send a test data in the formal request format, with isTest set to true in the Payload.

Test results can be viewed in Send History. Test sends do not affect real incidents and will not be counted in the formal send statistics.

Request Protocol¶

The system sends JSON data via POST with a request timeout of 5 seconds and does not follow redirects. The receiving service returning any 2xx status code is considered a successful delivery.

Request Header¶

Payload Example¶

{
  "eventId": "evt_01JXYZ...",
  "eventTypes": [
    "incident.created",
    "incident.status_changed"
  ],
  "eventTime": 1783000000,
  "workspaceUUID": "wksp_xxx",
  "incident": {
    "uuid": "incident_xxx",
    "name": "API service unavailable",
    "level": "level_1",
    "incidentsStatus": "working",
    "resourceType": "incident_aggregation",
    "aggregationRuleUUID": "rule_xxx",
    "aggregationRuleNameSnapshot": "生产环境服务聚合",
    "eventRelations": [
      {
        "df_fault_id": "fault_xxx",
        "status": "critical",
        "aggregationValues": {
          "df_workspace_name": "production",
          "df_dimension_tags.host": "web-01"
        }
      }
    ]
  },
  "isTest": false
}

Field descriptions:

incident Field Descriptions¶

incident is the incident snapshot at the time of sending. It will be updated as the incident's level, status, assignee, and associated events change.

Each item in eventRelations represents a currently associated event. Fields that are stably returned include:

Different event sources may carry additional fields. Third parties should identify associated events by df_fault_id and ignore unrecognized extension fields. For historical aggregated incidents, aggregationValues may be missing or empty; the receiving end should handle it compatibly. When the associated event snapshot or aggregation key-value of an aggregated incident changes, the "Aggregation Changed" event will be triggered.

Verify Request Source¶

The third-party receiving service should verify the Token, timestamp, and signature simultaneously.

The original text for signature is:

{timestamp}.{eventId}.{rawRequestBody}

Where rawRequestBody is the original request bytes received; do not format or re-serialize JSON first. It is recommended to only accept requests within 5 minutes before and after the current time, and deduplicate by eventId.

    import hashlib
    import hmac
    import time

    def verify_webhook(request, token):
        raw_body = request.get_data(cache=True)
        timestamp = request.headers.get("X-Incidents-Timestamp", "")
        event_id = request.headers.get("X-Incidents-Event-Id", "")
        signature = request.headers.get("X-Incidents-Signature", "")
        authorization = request.headers.get("Authorization", "")

        if not hmac.compare_digest(authorization, f"Bearer {token}"):
            return False
        if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
            return False

        message = f"{timestamp}.{event_id}.".encode("utf-8") + raw_body
        expected = "v1=" + hmac.new(
            token.encode("utf-8"), message, hashlib.sha256
        ).hexdigest()
        return hmac.compare_digest(expected, signature)

    import java.nio.charset.StandardCharsets;
    import java.security.MessageDigest;
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;

    boolean verify(byte[] rawBody, String timestamp, String eventId,
                   String signature, String authorization, String token) throws Exception {
        if (!MessageDigest.isEqual(
                authorization.getBytes(StandardCharsets.UTF_8),
                ("Bearer " + token).getBytes(StandardCharsets.UTF_8))) return false;

        byte[] prefix = (timestamp + "." + eventId + ".").getBytes(StandardCharsets.UTF_8);
        byte[] content = new byte[prefix.length + rawBody.length];
        System.arraycopy(prefix, 0, content, 0, prefix.length);
        System.arraycopy(rawBody, 0, content, prefix.length, rawBody.length);

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(token.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        String expected = "v1=" + java.util.HexFormat.of().formatHex(mac.doFinal(content));
        return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
                                     signature.getBytes(StandardCharsets.UTF_8));
    }

    import (
        "crypto/hmac"
        "crypto/sha256"
        "fmt"
    )

    func verifyWebhook(rawBody []byte, timestamp, eventID, signature, authorization, token string) bool {
        if !hmac.Equal([]byte(authorization), []byte("Bearer "+token)) {
            return false
        }
        content := append([]byte(timestamp+"."+eventID+"."), rawBody...)
        mac := hmac.New(sha256.New, []byte(token))
        mac.Write(content)
        expected := fmt.Sprintf("v1=%x", mac.Sum(nil))
        return hmac.Equal([]byte(expected), []byte(signature))
    }

Delivery and Send History¶

When multiple changes to the same incident occur within a short period for the same Webhook, the system will merge them into one delivery and return the types of changes included in this batch in the eventTypes of the Payload. The Payload always uses the latest incident snapshot at the time of sending.

The system does not automatically retry, nor does it support manual retry. You can view delivery results in Send History by send status, incident UUID, or event type; failed records will show response codes and error details for troubleshooting the third-party receiving service.