07.03 Webhook Integration

Why this matters

Webhooks are the standard pattern for real-time integration between SaaS applications: when something happens in App A, App A POSTs an event payload to a configured URL on App B. Slack notifications when a risk is filed, ServiceNow tickets when a mitigation is overdue, custom dashboards that update on audit completion — these are all webhook-shaped integrations.

The honest scope to know up front: SimpleRisk doesn't have generic outbound webhook support. There's no "Configure → Webhooks" page where you register https://my-system.example.com/sr-events and pick which SimpleRisk events should POST there. The only webhook integration in the codebase is the Jira Extra's inbound callback — it receives webhooks from Jira; it doesn't send webhooks to anywhere else. This article exists to spell that out so the integration conversation lands somewhere productive quickly.

The pragmatic path for "I need real-time SimpleRisk events in another system" is one of the alternatives listed below: poll the API, build a thin dispatcher, or use the Jira Extra if Jira is your downstream target.

What SimpleRisk does support

Inbound from Jira (via the Jira Extra)

The Jira Extra registers a webhook on Jira pointing at /extras/jira/callback.php?token=.... Jira POSTs jira:issue_created, jira:issue_updated, and jira:issue_deleted events to that callback; SimpleRisk processes them and updates the linked risk records. Authentication is via a query-string token. See The Jira Extra for the full configuration.

This is the only inbound webhook surface in the standard distribution.

Outbound: nothing native

There's no "Configure → Webhooks" surface. The application doesn't POST to external URLs on its own events. The codebase has no webhook_* settings table, no webhook-dispatcher cron, no per-event subscription model.

This is the limitation. If your integration plan assumed "SimpleRisk will POST to my endpoint," it won't.

What to do instead

Option A: Poll the v2 API

The most common pattern for moving SimpleRisk data to another system without native webhooks is API polling. A thin script:

Runs on a schedule (every 5 minutes, hourly, whatever fits).
Calls the v2 API for the data of interest (GET /api/v2/risks?modified_since=, or list and diff against your local cache).
For each new or changed entity, POSTs the relevant event to your downstream system.

Pros: works against the existing API; no SimpleRisk-side change needed; you control the dispatch logic.

Cons: latency depends on poll frequency; a 5-minute poll means up to 5-minute delay; high frequency means more API load.

For most "I need to push risk events to Slack" scenarios, a 1-5 minute poll is fine. Use a small script (Python, Node, Go) deployed alongside SimpleRisk; run it on cron or as a long-running service.

Option B: Use a workflow automation platform

Tools like Zapier, Make.com, n8n, and Tines specialize in connecting SaaS systems without custom code. They typically:

Poll SimpleRisk's API on a schedule.
Apply transformation logic.
Dispatch to the downstream system.

You configure the integration in their UI rather than writing code. Cost: a per-task or per-integration fee; reliability: high (they're built for this).

For programs without dedicated integration engineering capacity, a workflow platform is often the fastest path to production.

Option C: Use the Jira Extra if Jira is the integration target

If Jira is your downstream system anyway (and many integration paths funnel into Jira: a risk → a Jira ticket → engineering takes action → a Jira state change → SimpleRisk update), the Jira Extra natively handles the bidirectional sync. See The Jira Extra.

For scenarios where Jira sits in front of further systems (Jira automation rules dispatch to Slack, Microsoft Teams, ServiceNow), the SimpleRisk → Jira → downstream chain produces effective end-to-end integration without SimpleRisk needing direct webhook support.

Option D: Implement custom outbound webhook dispatch

For programs willing to invest in custom code, the path is:

Build a thin PHP file in simplerisk/extras/ / that hooks into SimpleRisk's existing event surfaces (the same hook points the Notification Extra uses).
On each event, dispatch a POST to your configured URL with a serialized event payload.
Handle retries, signing (HMAC), and dead-letter logic per your durability requirements.

This is meaningful engineering work — webhooks are deceptively complex once you account for retries, dedup, signing, and ordering. For most programs, options A–C are cheaper. But if your environment requires native dispatch (regulatory requirement that data not leave your infrastructure to a third-party automation platform, for example), custom development is the path.

Option E: Open a feature request

Native outbound webhook support is a recurring request and may ship in a future release. File the request via the SimpleRisk support channel; see Getting Help. Include the specific use case and the events you'd want to subscribe to.

What "outbound webhook support" would look like if added

For context, native outbound webhook support would likely include:

A Configure → Webhooks admin page where operators register webhook subscriptions: a URL, an event filter (which events to POST), an authentication mechanism (HMAC signing, bearer token, basic auth).
A webhook_subscriptions table storing the configuration.
Hook points in the Notification Extra's existing event-trigger code that dispatch to registered webhook subscriptions in addition to (or instead of) email.
A retry queue with backoff for failed POSTs.
A dead-letter queue for permanently-failed deliveries.
A per-webhook activity log (recent POST attempts, response codes, retry counts).
Per-webhook signing secrets so receivers can verify authenticity.

None of this exists today.

Common pitfalls

A handful of patterns recur with the "I want webhooks" conversation.

Assuming the Jira Extra's webhook is generic. It's Jira-specific. The callback URL only accepts Jira's payload shape; pointing other systems at it produces parse errors.
Building a polling integration without throttling. A poll every minute against the full risks list (which may return thousands of records) produces meaningful API load. Use modified-since queries, paginate appropriately, and batch.
Polling more frequently than you need. "Every 30 seconds" is usually overkill for risk events; 5–15 minutes is plenty for most operational use cases. Match poll frequency to the actual response-time requirement.
Using the unversioned /api/ URL in polling scripts. Use /api/v2/ explicitly. The unversioned URL is a transitional fallback that may behave differently across versions.
Storing the API key in the polling script's source. Use environment variables or a secrets manager. See API Key Management.
Building custom outbound dispatch without retry logic. Real network calls fail; without retries, a momentary outage on the receiver loses the event. Build retries from the start.
Treating workflow automation platforms as not-real integration. They are. For 80% of integration use cases, they're the right answer. The cost-benefit favors them over custom code unless there's a specific reason against (data residency, regulatory constraints, etc.).
Asking for "real-time" without quantifying latency. "Real-time" can mean anything from sub-second to "within a few minutes." Polling at 1-minute intervals is "real-time" for almost every GRC use case. Quantify the actual requirement before chasing sub-second integration.
Trying to make the Jira Extra dispatch to non-Jira targets by editing the callback URL. Don't. The Extra only knows how to talk to Jira. If you need a different downstream, use a different integration path.

The Jira Extra (the only native webhook integration; inbound from Jira)
Email and the Notification Extra
Using the API for Integrations (the polling alternative)
API Key Management
Getting Help