> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Receive notifications when events occur in incident.io.

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, keeping track of follow-ups in another system, or syncing on-call data like alerts, escalations, and schedule changes to external tools. Our webhooks are powered by [Svix](https://svix.com).

## 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](https://www.svix.com/play/) which lets you set up an endpoint and inspect payloads via their web interface. There are also other services (e.g. [ngrok](https://ngrok.com/)) which have great debugging tools.

Once you have a webhook endpoint set up, head to [Settings → Webhooks](https://app.incident.io/~/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](https://docs.svix.com/receiving/using-app-portal/replaying-messages) which you can access via [Settings → Webhooks](https://app.incident.io/~/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:

```json theme={null}
{
  "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](https://docs.svix.com/receiving/verifying-payloads/how) or [manually](https://docs.svix.com/receiving/verifying-payloads/how-manual).

## 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 a resource (incident, alert, escalation, or schedule)
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 resources

For private incidents, alerts, and escalations, webhook payloads only include the resource ID — not the full details. If your integration needs the full data, [create an API key](/integrations/api-overview) with private access and use it to fetch the details. This prevents leaking private information to systems that shouldn't have access.