SafeToOpen Browser Security

Ticketing & SIEM Integration

Overview and Setup Guide for Administrators

Guide 1 of 4 · September 2026

This guide explains how to connect SafeToOpen Browser Security to your ticketing system (ServiceNow, Jira, a PSA tool) or your SIEM, so that every security incident detected in your team’s browsers becomes a ticket your responders can work, and so that closing the ticket updates SafeToOpen in return.

It is written for the administrator of a Business Plus organisation or an MSP managing several customers. No SafeToOpen-specific software needs to be installed on your side; everything is configured in the Business Console and uses standard HTTPS, JSON and HMAC signatures.

The document set#

Guide	Read it when
1. Overview and Setup (this guide)	You are choosing an integration method and configuring it in the console.
2. ServiceNow Integration Guide	You want incidents in ServiceNow ITSM or Security Incident Response, including close-the-loop.
3. Jira Integration Guide	You want issues in Jira Software, Jira Service Management or Jira Data Center.
4. Webhook and API Reference	You are building your own receiver, relay, SOAR playbook or SIEM collector and need payloads, headers, signature code and error codes.

1. Concepts#

Events, incidents and severity#

The browser extension only reports pages it has flagged as a security concern. Each report is a security event with a severity of critical, high, medium, low, weak or info, an event kind describing what happened (for example a user typing credentials into a malicious page), the flagged URL, the member involved and the workspace they belong to.

Events appear on the Incidents page of the Business Console. Each has a review status: open, ok (reviewed, no issue) or issue (confirmed problem). The integration surface exposes exactly the same events, so what your SOC sees in a ticket is what an analyst would see in the console.

Workspaces#

A workspace is a named policy unit: a customer, a department or a domain. MSPs run one workspace per customer. Every integration is workspace-aware: a webhook can be limited to one or more workspaces, and an API token can be scoped so it can only ever read those workspaces’ events. This is how one console feeds several customers’ ticket queues without any cross-tenant leakage.

Three ways to integrate#

Method	How it works	Best for
Push · signed webhooks	SafeToOpen POSTs each incident to an HTTPS endpoint you provide, the moment it is recorded. Every delivery is HMAC-signed; failures are retried automatically.	Ticketing systems and SOAR platforms that can receive an inbound webhook (ServiceNow Scripted REST, Jira Automation, Azure Logic Apps, n8n, a small relay function).
Pull · export API	Your system polls a REST endpoint with a revocable token. Cursor-based paging means no gaps and no duplicates, in native JSON, OCSF, Elastic Common Schema or CEF.	SIEMs and log collectors (Splunk, Sentinel, Elastic, QRadar), scheduled jobs in ServiceNow, and environments that do not allow inbound connections.
Email-to-ticket	Per-workspace incident alert emails are sent to the intake mailbox of your ticketing or PSA tool.	A zero-code start, or PSA tools without an inbound webhook (ConnectWise, Autotask, HaloPSA email intake).

The methods can be combined: many customers push to ticketing and pull into the SIEM. Threat-intel platforms can additionally subscribe to a STIX 2.1 / TAXII 2.1 feed of hostile URLs (see the Reference guide).

Closing the loop#

When your responders resolve a ticket, the ticketing system can call the review endpoint so the incident is marked reviewed in SafeToOpen, attributed to the integration in the Activity log. Playbooks can also act, adding a URL to the organisation’s block or allow list. Both require a token with write-back enabled.

2. Prerequisites#

A SafeToOpen Business Plus organisation with the browser extension linked, and at least one workspace.
An Owner or Co-administrator account. Analysts cannot manage integrations.
For webhooks: an HTTPS endpoint with a public hostname and a valid certificate. Private or internal addresses, plain HTTP and credentials embedded in the URL are refused.
For the pull API: the egress IP addresses of your collector if you intend to use the optional IP allowlist.
For close-the-loop: the ability for your ticketing system to make outbound HTTPS calls to plus.safetoopen.com.

3. Set up a webhook (push)#

Sign in at https://plus.safetoopen.com and open the Business Console. Choose Integrations in the sidebar.
In the “Push · signed webhooks” card, click Add webhook.
Name — a label you will recognise, for example “ServiceNow intake” or “Jira – Customer A”.
Endpoint URL — the HTTPS address of your receiver. The console validates it immediately (HTTPS, resolvable, public address).
Workspaces — leave all selected for an organisation-wide feed, or tick only the workspaces this destination should receive. MSPs create one webhook per customer here.
Send — “All severities”, or “High & critical only” if the destination should only see incidents that need a human.
Click Add webhook. The signing secret is shown once. Copy it into your receiver’s secret store now; it cannot be displayed again.
Click Test on the new webhook. A signed sample event ("test": true, event id 0) is sent and the HTTP status your endpoint returned is shown.

Note Your receiver must answer with any 2xx status within 10 seconds. Anything else is treated as a failure and retried: after 1 minute, 5 minutes, 30 minutes and 2 hours. After 20 consecutive failures the webhook is disabled automatically and the event is written to the Activity log; re-enable it from the Integrations page once the endpoint is fixed.

Each webhook row shows its last delivery status and a Deliveries button listing the 20 most recent deliveries with attempts, timestamps and the last error. Any delivery can be re-queued with Redeliver.

Limits#

Up to 5 webhooks per organisation.
Delivery history is kept for 7 days.

4. Create an API token (pull and write-back)#

On the Integrations page, in the “Pull · export API” card, click Create token.
Name — for example “Splunk poller” or “ServiceNow close-the-loop”.
Workspaces — leave all selected for an organisation-wide token, or restrict it. A restricted token can never read, review or act outside its workspaces, even if it is stolen.
Allowed source IPs (optional) — the egress addresses of the calling system as exact IPv4/IPv6 addresses or IPv4 CIDR ranges, up to 20 entries. Calls from any other address are refused.
Allow write-back — tick this only for the system that will resolve tickets or run playbooks. Leave it off for SIEM pollers.
Click Create token. The token (sto_live_ followed by 48 hex characters) is shown once. Store it in your system’s credential vault.

Note Tokens are stored as a hash; SafeToOpen cannot show them again. Rotate replaces the secret immediately, so for zero-downtime rotation create a second token, switch the caller, then revoke the old one. Up to 10 active tokens are allowed per organisation, and each token is rate-limited to 240 requests per hour.

The console warns, but does not block, when two tokens cover the same workspace, since an MSP may legitimately run a customer’s own SIEM feed alongside a compliance job.

5. Set up email-to-ticket#

If your ticketing or PSA tool creates tickets from email, no code is needed:

Open Workspaces in the console and choose the workspace.
Under alert recipients, add the intake mailbox of your ticketing tool (for example the ConnectWise or HaloPSA email connector address).
Set the severity threshold and digest mode under Settings so the queue only receives what should become a ticket.

Alert emails group related events into one message and include the incident link, so a responder can jump from the ticket into the console. This method cannot close the loop automatically; use a webhook or the API when that matters.

6. Recommended ticket mapping#

The guides for ServiceNow and Jira implement this mapping. If you build your own receiver, it is a sensible default.

SafeToOpen field	Ticket field	Notes
`event.id`	Correlation / external id	Unique per organisation. Use it to deduplicate retried deliveries and to call the review endpoint later. Suggested value: `sto-<id>`.
`event.severity`	Priority	critical → P1, high → P2, medium → P3, low/weak/info → P4. Consider only forwarding high and critical to the on-call queue.
`event.event_kind` + `event.url_host`	Short description / summary	For example “[SafeToOpen] CRITICAL malicious_keyed – login-micros0ft.example”.
`event.url`	Description (defanged)	This is the hostile URL. Write it as text, never as a clickable link: replace `://` with `[://]` or `http` with `hxxp`.
`event.finding_reason`, `brand_match`, `trust_score`	Description	Why the page was flagged and which brand it imitated.
`event.member_email`	Affected user / caller	Look up the user record by email where your tool supports it.
`event.workspace`	Assignment group, customer or project	MSPs route by workspace: one workspace, one customer queue.
`event.occurred_at`	Opened at / event time	UTC, format `YYYY-MM-DD HH:MM:SS`.
Console link	Work notes	`https://plus.safetoopen.com/business-console#/incidents/<id>` opens the incident with full forensics for anyone with access.

7. MSP design pattern#

For a provider managing several customers from one console:

Push — One webhook per customer, filtered to that customer’s workspace, pointing at that customer’s queue (or at your own PSA with the workspace name routing the ticket to the right board).
Pull — One token per customer SIEM, scoped to that workspace, read-only, with the customer’s collector IP in the allowlist. Your own compliance or reporting job uses an unscoped read-only token.
Write-back — One write-back token for your central ticketing system so resolutions flow back for every customer. Keep it unscoped only if it also needs to block URLs organisation-wide; otherwise scope it too.
People — Customer staff who should see their own incidents are granted workspace-scoped analyst access in the console rather than an API token.

8. Security and privacy checklist#

Verify the X-STO-Signature header on every webhook delivery and reject timestamps older than 5 minutes. Code for every common platform is in the Reference guide.
Store the webhook secret and API tokens in the secret store of the receiving system, never in a script or a ticket.
Use workspace scoping and IP allowlists on tokens. A read-only token cannot change anything even if it leaks.
Treat the flagged URL as hostile data: display it defanged, never auto-link it, and never let automation open it.
Only flagged events leave the platform; normal browsing is never reported. Members you have redacted in the console are exported without identity or page details.
Events expire 365 days after they occurred and are no longer exported after that.
Every token and webhook change, and every review or block performed through the API, is recorded in the Activity log attributed to the token name (api:<name>).

9. Troubleshooting#

Symptom	Cause and fix
“URL must be https://” or “Host resolves to a private or reserved address” when adding a webhook	The endpoint must be public HTTPS. Internal hostnames, private IP ranges and plain HTTP are refused by design. Publish the receiver through a reverse proxy or a cloud function.
Test shows “test failed: HTTP 401/403”	Your receiver rejected the request. Most often the signature check is using a re-serialised body instead of the exact bytes received, or the endpoint requires an authentication header SafeToOpen does not send. Make the route public and rely on the signature.
Test shows “curl: …timeout”	The endpoint took more than 10 seconds or is unreachable from the internet. Check firewalls and the DNS record.
Webhook shows disabled	It failed 20 deliveries in a row and was switched off. Fix the endpoint, then enable it; pending deliveries can be re-queued with Redeliver.
API returns 401 `invalid_token`	The token was revoked or rotated, or the header is not exactly `Authorization: Bearer sto_live_…`.
API returns 403 `ip_not_allowed`	The caller’s public IP is not in the token’s allowlist. Add it or create a token without an allowlist.
API returns 403 `workspace_outside_token_scope` or `audit_requires_unscoped_token`	The token is workspace-scoped. The audit export and organisation-wide URL actions need an unscoped token.
API returns 429 `rate_limited`	More than 240 calls in an hour from one token. Poll less often and use `limit=500`.

Machine-readable documentation of every endpoint is published at https://plus.safetoopen.com/api/integrations/openapi (OpenAPI 3.0, YAML).