Skip to main content
Webhooks let you 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.

​
Getting started

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 lets you set up an endpoint and inspect payloads via their web interface. There are also other services (e.g. ngrok) which have great debugging tools. Once you have a webhook endpoint set up, head to Settings → Webhooks to configure it. From there you can choose which event types to receive, send test events, see recent deliveries, and retry any failed events.

​
Status codes, errors and retries

When processing webhooks, return a 2xx status code (e.g. 200 OK or 204 No Content). If your endpoint returns a non-2xx status code, we’ll retry with exponential backoff over the next 24 hours. If delivery attempts repeatedly fail over a 5 day period, we’ll disable the endpoint and notify you by email. If you miss some messages (e.g. due to unexpected downtime), Svix offers options for replaying messages which you can access via Settings → Webhooks.

​
Verifying webhooks

To verify that a webhook came from incident.io, check the signature in the request headers using the Signing secret from your webhook endpoint settings. Each webhook includes three headers: 
{
  "webhook-id": "123",
  "webhook-timestamp": 1676033031,
  "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
}
The signature is an HMAC of: 
$WEBHOOK_ID.$WEBHOOK_TIMESTAMP.$REQUEST_BODY
You can verify the signature using the Svix client libraries or manually.

​
Keeping another system in sync

A common use case is keeping another system up to date with incident.io. Since we deliver webhooks individually over HTTPS, they may not arrive in order. We recommend building your integration to:
  1. Receive a webhook about an incident (e.g. INC-123)
  2. Fetch the latest state from the API
  3. Save that state to your system
This way you don’t rely on webhook ordering for correctness.

​
Private incidents

For private incidents, webhook payloads only include the resource ID — not the full details. If your integration needs the full data, create an API key with private incident access and use it to fetch the details. This prevents leaking private incident information to systems that shouldn’t have access.