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) that have great debugging tools to help get started with webhooks.

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 failover 5 days, 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 offers several 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 a Signing secret.

The webhooks we send will have three headers that you’ll want to look at:

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 that:

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.

For more information, check out our API docs.