Implement any application or service with Zenduty using the Generic Integration.

To integrate any Applications Webhook with Zenduty, complete the following steps:

In Zenduty:

1. To add a new API integration, go to Teams on Zenduty and click on the team you want to add the integration to.
2. Next, go to Services and click on the relevant Service.
3. Go to Integrations and then Add New Integration. Give it a name and select the application Generic Integration from the dropdown menu.
4. Go to Configure under your integrations and copy the generated Webhook URL.

In your Application/Service:

5. To create an alert from your application, send a post request to above copied Webhook URL.

6. Add post parameters by following the table below :

   Name	Type	Default	Required	Example
   message	String	None	Yes	This becomes the incident title.
   summary	String	None	No	This is the incident summary.
   alert_type	String	Info	Yes	Choices - critical, acknowledged, resolved, error, warning, info.
   suppressed	Boolean	False	No	True or False
   entity_id	String	None	No	A unique id for the alert. If not provided, the Zenduty API will create one.
   payload	JSON	None	No	A JSON payload containing additional information about the alert.
   urls	Array	None	No	An array containing JSON schema of urls related to alerts.
   sla	String	None	No	Unique id of SLA. If not provided or invalid, then it will be ignored.
   escalation_policy	Strging	None	No	Unique id of Escalation Policy. If not provided or invalid, then it will be ignored.
   priority	String	None	No	Unique id of priority. If not provided or invalid, then it will be ignored.
   tags	Array	None	No	An array containing unqiue id of the tags.
   stakeholders	Dict	None	No	Dictionary containing three types of stakeholders i.e users, teams and emails. If not provided or invalid, then it will be ignored.
   stakeholders_comms	Dict	None	No	Dictionary containing subject, body of the stakeholder message. Also can provide timezone in which you want to convert date and time in email.

• In the headers, the Content type should be set to "application/json"

  Content-Type: application/json
  

• Sample Payload for creating an incident with a critical incident

{
  "alert_type": "critical",
  "message": "This is a sample alert from API integration",
  "summary": "This is the incident summary for the API integration",
  "entity_id": 12345,
  "payload": {
    "status": "ACME Payments are failing",
    "severity": "1",
    "project": "kubeprod"
  },
  "urls": [
    {
      "link_url": "https://www.example.com/alerts/12345/",
      "link_text": "Alert URL"
    }
  ]
}

• Detailed example of the payload structure, including optional parameters. Optional parameters can be ignored if they are not applicable to your requirements.

{
  "alert_type": "critical",
  "message": "This is info alert",
  "summary": "This is the incident summary",
  "entity_id": 12345,
  "payload": {
    "status": "ACME Payments are failing",
    "severity": "1",
    "project": "kubeprod"
  },
  "urls": [
    {
      "link_url": "https://www.example.com/alerts/12345/",
      "link_text": "Alert URL"
    }
  ],
  "sla": "cfb927ec-8316-4464-8770-deca07f75b49",
  "escalation_policy": "272841e2-2cbf-40a8-9a9a-64227fd3d722",
  "priority": "b535c8c0-7c75-4911-a9c6-27a3be2f2da9",
  "stakeholders": {
    "users": [
      "85e1569d-79a4-4205-850f-a",
      "b80daf25-8a47-4365-baa4-0"
    ],
    "teams": [
      "4a106e05-09af-4aef-9439-40c6f4aaff0f",
      "c1de7905-352f-424a-b8d0-f84406f76314"
    ],
    "emails": [
      "maryjane@sharklasers.com"
    ]
  },
  "tags": [
    "bdb4f470-b04b-4036-b8a4-5b66d9097b25",
    "ee99cc9c-a8ef-4a69-937c-07379e99d853"
  ],
  "stakeholders_comms": {
    "subject": "New incident #12345 triggered",
    "body": "We’re currently experiencing an incident affecting billing. Our team is actively working on it, and we’ll provide updates as soon as we have more information.",
    "timezone": "UTC",
    "created_by": "85e1569d-79a4-4205-850f-a"
    }
}

The alerts are bound into incidents by their entity ID. If you'd like to resolve the exising incident, make sure to change the alert type to 'Resolved' and keep the entity ID intact.

For example, you can send the below payload to resolve the above sample incident

{
  "alert_type": "resolved",
  "message": "This is a sample alert from API integration",
  "summary": "This is the incident summary for the API integration",
  "entity_id": 12345,
  "payload": {
    "status": "ACME Payments are failing",
    "severity": "1",
    "project": "kubeprod"
  },
  "urls": [
    {
      "link_url": "https://www.example.com/alerts/12345/",
      "link_text": "Alert URL"
    }
  ]
}

• For cURL requests:

 curl -X POST <IntegrationURL> -H 'Content-Type: application/json' -d '{"alert_type":"critical", "message": "This is a sample alert from API integration", "summary": "This is the incident summary for the API integration", "entity_id":"some_entity_id", "urls":[{"link_url": "https://www.example.com/alerts/1234/","link_text": "Alert URL"}]}'

• Response Status Codes are as below

• 200 OK: Message has passed the basic check and sent for further - processing.
• 400 Bad Request: Incorrect payload.
• 404 Not Found: Invalid integration key or Integration is disabled.

• Sample Payload for 200 OK Response

{
 "message": "success",
 "trace_id": "cadfe35f-e3b1-4175-b118-a595bff9a214"
} 

Status of an alert can be fetched using trace_id from the above response.

To get the status of an alert, use the following API endpoint:

https://events.zenduty.com/api/alert/status/<trace_id>/

• For a more detailed explanation of response schema, click here.

• The status of an alert can be one of the following: queued, failed, completed.

• Sample Payloads for Status Endpoint

{
 "status": "queued"
}

,

{
 "incident":{
	 "incident_number": 2524,
	 "unique_id": "cNasg9C4yzNpronzUUUdKR" 
},
 "alert": "U239RyRi7rySuJKb3FcKXE",
 "integration":{
	 "name": "Generic"
},
 "status": "completed",
 "is_incident_created": false,
 "suppressed": false
}

,

{
 "status": "failed",
 "error": "Your service is under maintenance" 
}

• Example of Alert Status Tracking Request

curl -L 'https://events.zenduty.com/api/alert/status/<trace_id>/'

Example Python Script for reference:

This script helps in getting incident details for references or modification of the incident in zenduty.

import requests
import time

# generic integration
# Example integration_webhook = "https://events.zenduty.com/integration/sdsds/generic/7e44896b-36c3-4fa2-b145-c292f543d8dc/"

integration_webhook = "<PASTE WEBHOOK URL>"
# api token with relevent permission
api_token = "<PASTE API TOKEN>"
data = {
  "alert_type": "critical",
  "message": "This is a sample alert from API integration",
  "summary": "This is the incident summary for the API integration",
  "entity_id": 12345,
  "payload": {
    "status": "ACME Payments are failing",
    "severity": "1",
    "project": "kubeprod"
  },
  "urls": [
    {
      "link_url": "https://www.example.com/alerts/12345/",
      "link_text": "Alert URL"
    }
  ]
}
# send alert to generic integration
response = requests.post(url=integration_webhook, json = data)

if response.status_code > 202:
    print(response)
    raise Exception("Something went wrong")
    
response = response.json()

print(response)

time.sleep(1)

# Poll the alert status endpoint until you get the status key in response
alert_status_response = {}
alert_status_response["status"] = "queued"

# alert_status_response["status"] can only be queued, failed, completed
while response['trace_id'] and alert_status_response["status"] not in ["failed", "completed"]:
    alert_status_response = requests.get(url = f"https://events.zenduty.com/api/alert/status/{response['trace_id']}/")
    time.sleep(1)
    alert_status_response = alert_status_response.json()
    print(alert_status_response)

# once you get the status as "success" then, in the payload you will find "is_incident_created", if it is true, that means new incident got created from the above alert
if alert_status_response["status"] == "completed" and alert_status_response["is_incident_created"]:
    headers = {"Authorization": f"Token {api_token}"}
    incident_response = requests.get(url=f"https://www.zenduty.com/api/incidents/{alert_status_response['incident']['unique_id']}/", headers = headers)
    print(incident_response.json())