How to Configure Outbound Event Webhooks in KC Safety

Last updated Aug 12, 2026

Summary

Outbound event webhooks let KC Safety notify another system the moment something happens — an incident is created, an incident changes status, an investigation is opened, or an action item is created. You register an HTTPS endpoint that you control, subscribe it to the events you care about, and KC Safety sends a JSON request to that endpoint each time a matching event occurs. This is the recommended way to push KC Safety events into other products in real time.

Introduction

Without webhooks, an external system has to ask KC Safety for updates on a schedule, which means either polling frequently and wasting requests, or polling rarely and reacting late. A webhook inverts that: KC Safety pushes the event to you as it happens.

A webhook is simply a URL you register in KC Safety. When a subscribed event occurs, KC Safety sends an HTTP POST to that URL with a JSON body describing what happened. Your receiver — a middleware service, an automation tool, or another product — verifies the request and acts on it.

Webhooks are configured by administrators and integration owners. You will need the Super Admin role and an HTTPS endpoint that is reachable from the public internet.

Key Concepts

Endpoint URL — the external HTTPS address you control that receives the requests. It must be publicly reachable and able to respond quickly.
Event subscription — the set of events an endpoint is registered for. KC Safety sends a request only when one of those events occurs.
Signing secret — a value you set on the endpoint and store on your side. KC Safety uses it to sign each request so you can prove the request came from KC Safety.
HMAC signature — the signature sent with each delivery, computed over the exact bytes of the request body using HMAC-SHA-256.
Retry with back-off — if a delivery fails, KC Safety tries again on an increasing delay rather than dropping the event.
Delivery log — the record of every delivery attempt and the response it received, available in the Webhooks interface.

Steps to Follow

Step 1: Open the Webhooks settings

Step 2: Register an endpoint URL

Add an endpoint and enter the destination URL. The URL must be a public HTTPS address that you control.

Note: Destination URLs are validated before they are accepted. Internal, private, and loopback addresses are rejected; redirects are not followed; and the response body returned by your endpoint is never stored or echoed back. Point webhooks only at public, internet-reachable HTTPS endpoints.

Select the events this endpoint should receive, or use * to receive all of them. Subscribing only to the events your system acts on keeps traffic focused and your receiver simpler.

These are the events KC Safety delivers:

Event	Fires when
`incident.created`	A new incident is created through any channel — the portal, inbound email, or the API.
`incident.status_changed`	An incident moves to a new status.
`investigation.created`	An investigation is opened on an incident.
`action_item.created`	A corrective or action item is created.
`test`	You use Send test on a webhook, to verify your receiver.

Note: These five events are the complete set that KC Safety delivers today. There is no separate event for an incident being closed, updated, or deleted. To react to a closure or any other transition, subscribe to incident.status_changed and inspect the new status in the payload. If you need a webhook tied to one specific workflow step rather than a global event, use the custom-workflow webhook action instead.

Step 4: Set a signing secret

Set a signing secret on the endpoint and store the same value securely on your side. KC Safety does not generate one for you, and without a secret your deliveries are unsigned — meaning your receiver has no way to confirm a request genuinely came from KC Safety. Setting a secret is strongly recommended.

Step 5: Send a test delivery

Use Send test to fire a sample test event at your endpoint. This confirms the URL is reachable and that your receiver accepts and verifies the request correctly before real events start arriving.

Step 6: Understand the delivery payload

Every delivery is a POST with a JSON envelope in this shape:

{
  "event": "incident.created",
  "timestamp": "2026-08-11T14:52:00.000Z",
  "account_id": "your-account-id",
  "data": {
    "incident": {}
  }
}

The data object carries the record the event is about: incident.created and incident.status_changed send data.incident, investigation.created sends data.investigation, and action_item.created sends data.action.

Step 7: Verify the signature on every delivery

KC Safety signs the raw request body with your endpoint's secret using HMAC-SHA-256 and sends the hex digest in the X-KC-Safety-Signature header. On your side, recompute the digest over the exact bytes you received — before parsing the JSON — and compare the two values with a timing-safe comparison. Reject any request whose signature does not match.

const crypto = require('crypto');

function isValid(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)            // the exact bytes received, before JSON.parse
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || '')
  );
}

Step 8: Handle retries and monitor deliveries

Return a 2xx response quickly. Deliveries time out after roughly 10 seconds, and any non-2xx response or timeout counts as a failed delivery. If your processing takes longer, acknowledge the request first and do the work asynchronously.

Failed deliveries are retried with exponential back-off — roughly 30 seconds up to about 2 hours, for up to 5 attempts per delivery.
An endpoint that keeps failing, after about 10 consecutive failures, is automatically disabled to protect your account. Fix your receiver, then re-enable the endpoint in the Webhooks interface.
Review the delivery log in the Webhooks interface to see what was sent and which response each attempt received.

Conclusion

Outbound event webhooks give you a dependable way to push KC Safety events into the systems that depend on them. Register a public HTTPS endpoint, set a signing secret, subscribe only to the events you act on, verify the signature on every request, and use the delivery log to confirm receipt or diagnose failures. Because only the five events listed above are delivered, use incident.status_changed for closures and other transitions rather than looking for a dedicated event.