Webhooks

Webhooks can be used to receive notifications when certain events occur in incident.io. This might be useful for annotating graphs in a monitoring tool with incidents, or keeping track of follow-ups in another system. Our webhooks are powered by Svix.

To start using webhooks, you’ll need to create a webhook endpoint. You can do this in the same way that you’d create any other endpoint in your application. If you’d like to play around with our webhooks, we’d recommend using Svix play which allows you to set up an endpoint and inspect the payloads via their web interface. There are also other services (e.g. ngrok) which have great debugging tools to help getting started with webhooks.

Once you have a webhook endpoint set up, you can head to Settings > Webhooks to configure your endpoint. In here you'll be able to choose which types of events you'd like to recieve, send test events, see recent event deliveries, and retry any failed events.

When processing webhooks, please return a 2xx status code (e.g. 200 OK or 204 No Content). If the endpoint returns a non-2xx status code, we’ll try to resend the event with a backoff over the next 24 hours. If attempts to a specific endpoint repeatedly fail over a 5 day period, we’ll mark the endpoint as disabled and notify you via email. If you do miss some messages (e.g. due to unexpected downtime), Svix offer a number of options for replaying messages which you can access via Settings > Webhooks.

It’s important to know whether a webhook has come from incident.io, or a third party that might be trying to exploit a vulnerability. To avoid this, we send a signature in the header of our webhooks, which you can verify using the Signing secret from the webhook endpoint settings page. The webhooks we send will have three headers that you’ll want to look at:

{
  "webhook-id": "123",
  "webhook-timestamp": 1676033031,
  "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
}

These are signed using a HMAC signature in the following format:

${webhook-id}.${webhook-timestamp}.${request_body}

You can verify the signature either using the Svix client libraries, or manually by following these instructions.

A common use-case for webhooks is to keep another system up-to-date with everything that’s happening in incident.io. As we deliver webhooks individually over HTTPS, we cannot guarantee that they’ll be delivered in the correct order. That means that, to keep the other system up-to-date, we’d recommend that you build an application which:

• Receives a webhook about INC-123
• Makes a request to our public API to get the latest state of INC-123
• Save that state to your system

This means you aren’t relying on the order in which you receive webhooks to make sure your system remains up-to-date.

In general, we try to send webhooks with all the relevant information in the payload (e.g. the name, summary, status etc.). However, private incidents are the exception. For private incidents, we only send the ID of the resource that’s been changed. If your integration needs to access the full data, you’ll need to create an API Key that can view private incidents. You can then use that key to get the details about the specific incident or follow-up. This is to make sure we don’t leak information about private incidents to a system that shouldn’t have access to them.