Skip to main content

Integrations

API Integration Guide

⚠️
[IMPORTANT] We're phasing out the API-Integration in favour of the Generic Integration. Starting October 15th, 2024, no new API-Integration integrations can be created. We will continue to support the existing API-Integrations until March 31st, 2025, after which they will stop working. We recommend you to migrate the existing API-Integrations to the Generic Integration at your earliest convenience.

The API Integration allows you to send alerts from any system to Zenduty and trigger and resolve alerts.

To integrate any Application's 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 API from the dropdown menu.
  4. Go to Configure under your integrations and copy the Integration key generated.

In your Application/Service:

  1. To create an alert from your application, send a post request to:
    https://events.zenduty.com/api/events/<integration-key>/
  • Here, the integration key that was copied earlier is to be used.

  1. Add post parameters by following the table below :

    Name Type Default Example Required
    message String None This becomes the incident title. Yes
    summary String None This is the incident summary. No
    alert_type String Info Choices - critical, acknowledged, resolved, error, warning, info. Yes
    suppressed Boolean False True or False No
    entity_id String None A unique id for the alert. If not provided, the Zenduty API will create one. No
    payload JSON None A JSON payload containing additional information about the alert. No
    urls Array None An array containing JSON schema of urls related to alerts. No
  • In the headers, the Content type should be set to "application/json"
  • 'Content-Type: application/json'
  • For a more detailed explanation of the fields, click here.
  • 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"
    }
  ]
}

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 https://events.zenduty.com/api/events/[integration-key]/ -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"}]}'
Zenduty SignUp