Webhooks

Webhooks provide real-time, event-driven communication between RiskOS™ and your applications. When specific events occur in RiskOS™ (such as decision changes in Case Management), HTTP POST requests are automatically sent to your configured endpoints with relevant event data.

Webhook testing tools

To quickly verify that events are being successfully triggered and sent by RiskOS™, you can use Webhook Cool (or a similar tool), which will provide you with a unique URL to receive the events.

⚠️

Security note:

When using external testing tools like Webhook Cool, please be mindful that your webhook payload will contain your authorization as well as sensitive customer information (depending on your workflow configuration). RiskOS™ does not endorse this third-party tool and is not responsible for the security or handling of data received by Webhook Cool or any other external service. Use such tools only for non-production testing and with awareness of the data being exposed.

Quick start

Manage webhooks

Users with the appropriate permissions can configure and manage their webhooks on the Developer Workbench > Webhooks section of the RiskOS™ Dashboard.

The Webhooks section displays all configured webhooks along with key details:

• Webhook URL: Destination endpoint that receives event payloads.
• Created / Last Modified: When the webhook was created or last updated.
• Subscribed Events: Event types that trigger the webhook.

Delete a webhook

Click the trash icon for the webhook, then confirm Delete.

Advanced webhook settings

Header variables

RiskOS™ supports static header variables. For setup, contact your Solutions Consultant.

Retry mechanism

If delivery fails due to specific HTTP responses, RiskOS™ retries up to 10 times with exponential backoff:

• Backoff grows up to 60 seconds.
• From the 6th attempt onward, retries occur at 1-minute intervals (for the remaining 4 attempts).
• Retries occur on: 504, 503, 502, 429, 423, 409, 408.
• Design for idempotency using event_id to avoid duplicate processing.

IP allowlisting

Allow outbound calls from RiskOS™ to your endpoint:

• Sandbox: 35.230.191.253/32
• Production: 35.199.32.202/32, 3.138.161.243

👍

Tip:

If you use a WAF or API gateway, add these to source IP allowlists and confirm with an end-to-end test.

Security recommendations

• Use HTTPS and one of the supported auth methods (Basic, Bearer, OAuth2).
• Validate inputs: treat payloads as untrusted; enforce JSON schema and size limits.
• Store minimal data from the webhook; fetch additional details from your backend if needed.
• Log event_id, event_type, and event_at for observability and replay support.

Sample receivers

Use the code samples below as a starting point. They acknowledge quickly and de-duplicate via event_id.

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json({ type: "application/json" }));

// Replace with a real, persistent store:
const seen = new Set();

app.post("/webhooks/riskos", async (req, res) => {
  const { event_id, event_type, data } = req.body || {};
  if (!event_id || !event_type) return res.status(400).send("Bad Request");

  // Idempotency: drop duplicates
  if (seen.has(event_id)) return res.status(200).send("OK");
  seen.add(event_id);

  // Queue async work (do not block the response)
  queueMicrotask(() => handleEvent(event_type, data).catch(console.error));

  return res.status(200).send("OK");
});

async function handleEvent(type, data) {
  switch (type) {
    case "evaluation_completed":
      // process...
      break;
    default:
      // no-op
  }
}

app.listen(3000, () => console.log("Listening on :3000"));

from flask import Flask, request, jsonify

app = Flask(__name__)
seen = set()  # replace with durable store

@app.post("/webhooks/riskos")
def riskos():
    payload = request.get_json(silent=True) or {}
    event_id = payload.get("event_id")
    event_type = payload.get("event_type")
    data = payload.get("data")

    if not event_id or not event_type:
        return ("Bad Request", 400)

    if event_id in seen:
        return ("OK", 200)
    seen.add(event_id)

    # Do processing async/off-thread in production
    handle_event(event_type, data)
    return ("OK", 200)

def handle_event(event_type, data):
    if event_type == "evaluation_paused":
        pass  # handle
    # etc.

if __name__ == "__main__":
    app.run(port=3000)

Troubleshooting