We’re building incident.io as the single place you turn to when things go wrong. When an issue is disrupting your business-as-usual, the last thing you want is to start opening ten different tools to diagnose and fix it!
As your central incident hub, we need to give you two powers:
🔌 What does the incident.io API do?
The API currently allows for:
Automatically creating an incident from another system, such as a monitoring tool like Datadog, or a ticketing system like Zendesk
Exporting incidents and their to-dos into a data warehouse or BI tool (Looker, Tableau etc.) to analyse.
Needless to say though, we’ll be extending this over time, so we’d love to hear what you’d like to use our API for!
🔑 Where can I find the API Keys?
You can create your API Keys from the API section of your incident.io Settings if you are on a Pro or Enterprise plan.
💬 Example use case: declaring an incident from Zendesk
You might use a ticketing system like Zendesk (or Freshservice; or Intercom) to manage your customer support. Inbound tickets are typically triaged by customer support teammates, and escalated to engineering teams based on specific criteria (e.g. a certain severity, or a particular incident type such as data breaches).
With our API, a support agent can declare an incident with one click, straight from within Zendesk. We’ll take care of the rest, from declaring the incident in incident.io to pulling in the right teammates, notifying the relevant internal and external stakeholders, spinning up your public Statuspage and much more.
Here are the few key steps to bringing this flow to life.
1️⃣ Generate an API Key in incident.io
You’ll want to generate a key with
Create incidents enabled. Keep this safe - we’ll need it in a minute.
This lets you choose when Zendesk should escalate a ticket. In this case, we might use a checkbox custom field, which will declare an incident when it’s ticked.
3️⃣ Add a Zendesk webhook as the action to take when the trigger fires
Configure it to make an HTTP POST request to
https://api.incident.io/v1/incidents. The API Key we generated earlier is used for Bearer token authentication. The request body needs to be JSON that looks like:
There’s a couple of special IDs in there you’ll need:
That’s it! 🎉 Whenever that trigger fires, you’ll get a new incident declared in Slack. Nice.
Even nicer: you can configure workflows that only run on your API-generated incidents.
For example, you could build a workflow that automatically adds the support agent that declared the incident in Zendesk to the incident’s Slack channel. To do that, add a Condition based on the API Key that reported the incident. This would look like:
📈 Exporting incident data to your warehouse
Data is always more powerful when you can link it together, which is why most organisations want to have all their different systems synced into a data warehouse where things can be analysed in one place.
With our API, you can get all your incident, action, and follow-up data out of incident.io and into your warehouse. There are two key APIs here:
By scraping each of these once an hour, you can pull in everything we know about all your incidents and link that with any other data in your warehouse. If you have your Jira data there you can link followups in incident.io with the corresponding ticket in Jira, for example.
📘 Keeping in sync with your service catalog
One of the most common uses of custom fields is to tag incidents with which teams and services were involved. You can keep those lists in sync with your service catalog, using the Custom Field Options API.
This API lets you manage options for any custom field. Beyond Custom Fields, you can also manage custom Incident Roles and Severities using the API, if you want to keep all your configuration in a central location, for example using Terraform.
Over to you!
We built our API around these two use-cases for now, but we’ll be expanding it, for example to customise and configure your incident.io incidents (e.g. uploading your service catalogue).
We’d absolutely love to hear what you build with it, and how you’d like us to extend it.
#api channel in the incident.io Community. See you there 👀