How to Trigger a Webhook from a KC Safety Workflow Transition

Summary

Besides the webhook endpoints you register globally, a KC Safety workflow transition can fire a one-off webhook to a URL stored on the rule itself. You add a "Trigger webhook" action to a status transition in your workflow, and KC Safety calls that URL whenever an incident makes that specific transition. This is useful when the notification belongs to one particular workflow step rather than to an event across the whole account.

Introduction

Registered webhooks subscribe an endpoint to an event type across your entire account: every status change fires the same notification to the same place. That is the right model most of the time, but not always.

Sometimes only one step in your process matters to an external system. You might want to call an approval service when an incident moves to "Pending Review", or notify a contractor's system only when work is handed over. Subscribing globally to incident.status_changed would deliver every transition and leave the receiver to filter out the ones it does not care about.

The custom-workflow webhook action solves this by attaching the URL to the transition itself. No registered endpoint is needed, and only that transition triggers a call.

Key Concepts

• Workflow transition — a move from one incident status to another, as defined in your workflow configuration.
• Trigger webhook action — an action you attach to a transition that calls a URL when the transition occurs.
• workflow.transition payload — the request body sent by this action, which is distinct from the payloads sent by registered event webhooks.
• Unsigned delivery — these requests are not HMAC signed, so the receiver cannot verify origin from a signature.

Steps to Follow

Step 1: Open your workflow settings

Sign in as an administrator and go to Admin Panel → Settings → Workflows. Open the workflow that contains the transition you want to act on.

Step 2: Add a Trigger webhook action to the transition

Select the status transition that should fire the call, add a Trigger webhook action to it, and enter the destination URL. The URL is stored on the rule, so you do not need to register an endpoint under Settings → Integrations → Webhooks.

Step 3: Confirm the URL meets the same requirements as registered webhooks

The same destination validation applies here as for registered webhooks: the URL must be a public HTTPS address you control. Internal, private, and loopback addresses are rejected, and redirects are not followed.

Step 4: Handle the payload on your side

This action sends a workflow.transition payload, which is a different shape from the incident.created and incident.status_changed payloads that registered webhooks send. If the same receiver handles both, branch on the event so you do not try to read a registered-webhook payload out of a workflow delivery, or the reverse.

Step 5: Protect the endpoint, since deliveries are unsigned

Unlike registered webhooks, workflow webhook deliveries are not signed, so there is no X-KC-Safety-Signature header to verify. Compensate for that:

• Treat the URL itself as a credential. Use a long, unguessable path or include a random token in the URL, and store it as a secret.
• Validate the payload before acting on it, and make the handler safe to call more than once with the same input.
• Do not let the endpoint perform destructive or irreversible actions on the strength of an unauthenticated call alone.

Note: When you need verifiable, signed deliveries — or retries and a delivery log — use a registered outbound event webhook instead, and subscribe it to incident.status_changed. Registered webhooks are signed with your endpoint's secret, retried with back-off, and recorded in the delivery log. The workflow action trades those properties for the ability to target one specific transition.

Conclusion

The custom-workflow webhook action is the precise tool for calling an external system at one specific point in your incident process. Add the action to the transition, point it at a public HTTPS URL, and branch on the workflow.transition payload in your receiver. Because these deliveries are unsigned, keep the URL secret and the handler defensive — and choose a registered outbound webhook when signature verification, retries, or delivery history matter more than targeting a single transition.