Webhook and API Reference

This reference is for engineers building a receiver, relay, SOAR playbook or SIEM collector. The base URL for every endpoint is https://plus.safetoopen.com/api. A machine-readable OpenAPI 3.0 description is published at https://plus.safetoopen.com/api/integrations/openapi.

1. Webhook deliveries (push)#

1.1 Request#

1.2 Payload#

{
  "type": "browser_security.flagged_event",
  "version": 1,
  "sent_at": "2026-09-02T10:15:07+00:00",
  "business_id": 42,
  "event": {
    "id": 2640,
    "occurred_at": "2026-09-02 10:15:00",
    "event_kind": "malicious_keyed",
    "severity": "critical",
    "workspace": "acme.com",
    "member_email": "[email protected]",
    "url": "https://login-micros0ft.example/verify",
    "url_host": "login-micros0ft.example",
    "url_sha256": "9f2c0e…",
    "trust_score": 4,
    "finding_id": "brand_lookalike",
    "finding_reason": "Login page imitating Microsoft on an untrusted domain",
    "brand_match": "microsoft",
    "page_title": "Sign in to your account",
    "referrer_host": "mail.google.com"
  }
}

1.3 Verifying the signature#

Compute the HMAC over the exact bytes of the request body, prefixed by the timestamp and a dot. Compare in constant time and reject timestamps more than 5 minutes from your clock. Do not parse and re-serialise the JSON before verifying; any change in whitespace or key order breaks the signature.

Python (Flask)#

import hmac, hashlib, time, json, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["STO_WEBHOOK_SECRET"].encode()

@app.post("/sto/webhook")
def sto_webhook():
    raw = request.get_data()                                   # exact bytes
    parts = dict(kv.split("=", 1) for kv in request.headers.get("X-STO-Signature", "").split(",") if "=" in kv)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        abort(401)
    expected = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)
    data = json.loads(raw)
    if data.get("test"):
        return "", 200
    handle_event(data["event"])                                # idempotent on event["id"]
    return "", 200

Node.js (Express)#

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/sto/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries((req.get('X-STO-Signature') || '').split(',').map(kv => kv.split('=')));
  if (!/^\d+$/.test(sig.t || '') || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return res.sendStatus(401);
  const expected = crypto.createHmac('sha256', process.env.STO_WEBHOOK_SECRET)
                         .update(sig.t + '.').update(req.body).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(sig.v1 || ''));
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);
  const data = JSON.parse(req.body.toString('utf8'));
  if (!data.test) handleEvent(data.event);
  res.sendStatus(200);
});

PowerShell (Azure Functions)#

param($Request, $TriggerMetadata)
$raw  = $Request.RawBody                     # string of the exact body
$hdr  = $Request.Headers['X-STO-Signature']
$t    = ($hdr -split ',' | Where-Object { $_ -like 't=*' })  -replace '^t=', ''
$v1   = ($hdr -split ',' | Where-Object { $_ -like 'v1=*' }) -replace '^v1=', ''
$now  = [int][double]::Parse((Get-Date -UFormat %s))
if (-not ($t -match '^\d+$') -or [math]::Abs($now - [int]$t) -gt 300) { Push-OutputBinding -Name Response -Value @{ StatusCode = 401 }; return }
$hmac = New-Object System.Security.Cryptography.HMACSHA256
$hmac.Key = [Text.Encoding]::UTF8.GetBytes($env:STO_WEBHOOK_SECRET)
$hash = $hmac.ComputeHash([Text.Encoding]::UTF8.GetBytes("$t.$raw"))
$expected = ($hash | ForEach-Object { $_.ToString('x2') }) -join ''
if ($expected -ne $v1.ToLower()) { Push-OutputBinding -Name Response -Value @{ StatusCode = 401 }; return }
$data = $raw | ConvertFrom-Json
if (-not $data.test) { Handle-Event $data.event }
Push-OutputBinding -Name Response -Value @{ StatusCode = 200 }

The Reference relay in the Jira guide and the Scripted REST script in the ServiceNow guide show the same check in those environments.

1.4 Receiver checklist#

• Respond 2xx quickly (under 10 s) and do the work asynchronously if ticket creation is slow.
• Deduplicate on event.id; a retried delivery carries the same payload.
• Return 5xx when you want SafeToOpen to retry, 2xx when you have accepted the event even if you chose to ignore it.
• Ignore payloads with "test": true.

2. Export API (pull)#

2.1 Authentication and limits#

2.2 GET /integrations/events#

Response:

{
  "events": [ { "id": 2640, "type": "browser_security.flagged_event", "occurred_at": "2026-09-02 10:15:00",
                "received_at": "2026-09-02 10:15:03", "event_kind": "malicious_keyed", "severity": "critical",
                "workspace": "acme.com", "member_email": "[email protected]", "member_name": "Jane Doe",
                "url": "https://login-micros0ft.example/verify", "url_host": "login-micros0ft.example",
                "url_sha256": "9f2c0e…", "trust_score": 4, "finding_id": "brand_lookalike",
                "finding_reason": "Login page imitating Microsoft on an untrusted domain",
                "brand_match": "microsoft", "page_title": "Sign in to your account",
                "referrer_host": "mail.google.com", "review_status": "open",
                "client_ip": "203.0.113.7", "member_redacted": false } ],
  "next_since_id": 2640,
  "has_more": false
}

Compared with the webhook payload, the export adds received_at, member_name, review_status (open, ok, issue), client_ip and member_redacted. For members redacted in the console, identity and page fields are null and member_redacted is true.

Polling loop#

#!/usr/bin/env python3
# Poll SafeToOpen every few minutes; keeps the cursor in a file. Run from cron.
import json, os, sys, urllib.request
TOKEN = os.environ["STO_TOKEN"]; STATE = os.path.expanduser("~/.sto_since_id")
since = int(open(STATE).read() or 0) if os.path.exists(STATE) else 0
while True:
    req = urllib.request.Request("https://plus.safetoopen.com/api/integrations/events?since_id=%d&limit=500" % since,
                                 headers={"Authorization": "Bearer " + TOKEN})
    with urllib.request.urlopen(req, timeout=30) as resp:
        page = json.load(resp)
    for ev in page["events"]:
        print(json.dumps(ev))            # or forward to your ticketing / SIEM
    since = page["next_since_id"]
    open(STATE, "w").write(str(since))
    if not page["has_more"]:
        break

Schema variants#

• OCSF — format=ocsf — OCSF 1.1 Detection Finding (class_uid 2004). Severity maps to severity_id 1–5, status is New or Resolved, the URL is in resources[0].data.url_string, SafeToOpen-specific fields in unmapped.
• ECS — format=ecs — Elastic Common Schema documents with @timestamp, event.kind: alert, event.severity 10–99, url.full, user.email, labels.workspace and a safetoopen object.
• CEF — format=cef — each item is a string: CEF:0|SafeToOpen|BrowserSecurity|1.0|<event_kind>|<reason>|<1-10>|externalId=… request=… dhost=… suser=… cs1Label=workspace cs1=….

2.3 Audit export#

GET /integrations/events?type=audit&since_id=… returns administrative actions for compliance monitoring, each as { id, type: "browser_security.audit", occurred_at, action, actor, actor_ip, detail }. Actions include policy changes, URL list changes, member and workspace changes, analyst grants, token and webhook changes, and every review made through the API. Requires an unscoped token.

3. Write-back#

3.1 POST /integrations/review#

Marks an event reviewed from your ticketing system. Requires a token with write-back.

POST /api/integrations/review
Authorization: Bearer sto_live_…
Content-Type: application/json

{ "event_id": 2640, "status": "issue" }      // "ok" = reviewed, no issue; "open" = reopen

200 { "success": true, "event_id": 2640, "status": "issue" }

The review appears in the console and in the Activity log as “event reviewed via api:<token name>”. A workspace-scoped token receives 404 for events outside its scope, so scopes never leak existence.

3.2 POST /integrations/action#

Adds a URL to the organisation’s block or allow list, the same path an administrator uses in the console. Requires an unscoped write-back token; limited to 60 calls per hour.

POST /api/integrations/action
Authorization: Bearer sto_live_…
Content-Type: application/json

{ "action": "block_url", "url": "https://login-micros0ft.example/verify", "category": "phishing" }

200 { "success": true, "action": "block_url", "url": "https://login-micros0ft.example/verify" }

category is free text (default soar_playbook) and appears in the console’s URL list and Activity log. allow_url works the same way.

4. Threat intelligence#

• STIX bundle — GET /integrations/stix?since_id=&limit= returns a STIX 2.1 bundle of hostile-URL indicators for critical and high events. Response headers X-STO-Next-Since-Id and X-STO-Has-More drive incremental pulls.
• TAXII 2.1 — Discovery URL https://plus.safetoopen.com/api/taxii2/, one collection named indicators. Authenticate with HTTP Basic using any username and the token as the password, or a Bearer header. MISP, OpenCTI and similar platforms subscribe directly.

5. Event kinds and severities#

Event kinds are strings up to 48 characters set by the detection engine. Map the ones below explicitly and treat anything else with a default mapping; new kinds may appear as detection improves.

Suggested priority mapping: critical → P1, high → P2, medium → P3, low, weak, info → P4. Webhooks can be limited to high and critical in the console.

6. Error codes#

7. Security notes#

• Webhook destinations must be public HTTPS; SafeToOpen resolves the host, refuses private and reserved addresses, and pins the connection to the vetted IP so DNS changes cannot redirect a delivery.
• Secrets and tokens are shown once and stored hashed. Revoking a token or deleting a webhook takes effect immediately.
• Every call that changes state (review, action) and every token or webhook change is written to the Activity log attributed to api:<token name> or the administrator.
• The flagged URL is the indicator your SOC needs, which is why it is included in clear text. Handle it as hostile: defang it in tickets and never let automation open it.