Webhook Subscriptions
Webhooks let you push Incido events to your own systems in real time. When an incident is created, a maintenance starts, or a status changes, Incido sends an HTTP POST request to the endpoint you configure. This enables automation that would otherwise require polling the API — triggering PagerDuty escalations, updating internal dashboards, posting to Slack channels, syncing with ticketing systems, or driving any custom workflow your team needs.
Webhooks require the Webhook Notifications feature on your plan.
Creating a webhook subscription
A webhook subscription defines where events are sent, which events matter to your workflow, and how your receiver validates deliveries.
Endpoint URL is the HTTPS URL that receives webhook payloads. It must be publicly reachable. Incido validates endpoint reachability when subscriptions are configured and during delivery.
Event types define which events trigger a delivery to this subscription. You must select at least one. The available event types are:
incident-created— a new incident was created.incident-updated— an incident received a status change or update.incident-closed— an incident reached the Closed stage.maintenance-created— a new maintenance was created.maintenance-started— a maintenance moved to In Progress.maintenance-updated— a maintenance received a status change or update.maintenance-closed— a maintenance reached the Closed stage.
Choose event types deliberately. Subscribing to everything when you only need incident closures creates unnecessary load on both sides and makes your receiver logic more complex than it needs to be.
Custom headers are optional HTTP headers included with every delivery. Use them for authentication tokens, routing metadata, or contextual values your receiving system needs.
Your organization can have up to 15 webhook subscriptions.
Payload format and signing
Every webhook delivery is an HTTP POST with a JSON payload containing an event identifier, event type, payload data, and timestamp.
Payloads are signed so your receiver can verify authenticity before processing events. Signature verification is strongly recommended because it confirms the payload originated from Incido and was not altered in transit.
Each delivery includes headers that tell your receiver which RSA key signed the body. Signature-Key-Id is the public identifier for that key, always in prefixed form: whk_ followed by exactly 32 lowercase hexadecimal digits (no hyphens). Signature-Key-Url is the absolute URL of the Incido API route that returns the matching public key as plain text; the path segment after /webhook-keys/ and before /public-key is that same prefixed value. When you fetch the key or compare identifiers in your own logs, use the prefixed string exactly as Incido sends it.
Delivery and retry behavior
Webhook deliveries are dispatched asynchronously after the triggering action commits. Incido gives your endpoint 3 seconds to respond with a 2xx status code. If the request times out, returns a non-2xx response, or fails due to a connection error, Incido retries with exponential backoff.
The retry schedule uses a short exponential backoff window after the initial attempt. If all retries fail, the delivery is marked as permanently failed and no further retries are made.
At delivery time, the endpoint URL is re-validated. If DNS resolution fails or the URL is no longer publicly reachable, the delivery is logged as failed immediately without attempting the request.
Design your receiver to be idempotent — the same event may arrive more than once if a previous delivery appeared to fail from Incido's perspective but actually succeeded on your side (for example, a network timeout after your server processed the request).
Delivery logs
Every delivery attempt is logged with the full request payload, the response (if any), the HTTP status code, the number of attempts, and whether the delivery ultimately succeeded or failed. You can review these logs in the Dashboard to diagnose integration issues.
Delivery logs and soft-deleted webhook subscriptions are automatically cleaned up after 30 days.
What changes on the public frontend
Webhook subscriptions have no direct effect on your public status pages. Customers do not see webhook configuration or delivery activity. However, automations built on top of webhook events can indirectly affect what people outside your team see.
Operational effects
Webhook subscriptions are part of your external communication and automation chain. If endpoint reliability or receiver validation is weak, downstream workflows such as paging, ticketing, or reporting can silently break even while the public status page remains correct. Keep webhook behavior aligned with Incidents, Maintenances, and Subscribers to avoid split-brain communication.
Troubleshooting
Webhook deliveries are failing. Check the delivery logs in the Dashboard for the specific error. Common causes: your endpoint is returning a non-2xx status code, the endpoint URL is unreachable (DNS failure, firewall rules, expired SSL certificate), or the 3-second timeout is too short for your receiver's processing time.
You are not receiving events you expect. Verify the subscription's event type selection includes the events you are waiting for. Check that the subscription is active and not soft-deleted. Confirm that the triggering action actually occurred (for example, an incident must be closed, not just resolved to Post Incident, to trigger incident-closed).
Signature verification fails on your side. Confirm you are using the current public key from the key endpoint. If the signing key was recently rotated, your cached public key may be stale. Retrieve the latest key and retry verification.
You hit the subscription limit. Your organization can have at most 15 webhook subscriptions. Remove unused subscriptions to make room for new ones.