Alert Routing

Alert Routing lets your organization forward security alerts from any of your managed tenants to the places your team actually watches: a SOC webhook receiver, a Slack- or Teams-style incoming webhook, or a PagerDuty on-call service. Instead of configuring alert forwarding tenant by tenant, you define routes once at the organization level and they apply across your managed tenants.

Routes are evaluated as alerts arrive, so a critical phishing alert raised in one tenant at 2 a.m. can page your on-call engineer without anyone having signed in to that tenant. The page lives at Control > Alert Routing in the organization sidebar.

Screenshot

[SCREENSHOT PLACEHOLDER: The Alert Routing page showing two route cards - one enabled webhook route with a "Secret configured" badge and one disabled route with a "Disabled" badge - plus the "New route" button in the top right.]

How it works

Every time an alert is written in one of your managed tenants, Surface checks it against your organization's enabled routes. A route fires when all of its conditions match:

• The alert's severity is at or above the route's Minimum severity.
• The alert's type is allowed by the route's alert-type filter (routes created from this page match all alert types).
• The alert's tenant is inside the route's tenant scope (see below).

Matching deliveries are sent asynchronously, off the ingestion path - a slow or unreachable destination never delays alert processing or the extension fleet. Each delivery gets a bounded time window (about 15 seconds); deliveries that fail are recorded in the service logs but are not retried, so use the Test button to confirm a destination works before you rely on it.

Routes are strictly organization-scoped: a route in your organization can only ever fire for alerts raised in your own managed tenants.

Tenant scope

When you save a route, it is bound to the managed tenants your account has access to at that moment. The route card shows this as the number of tenants it covers (for example, 3 tenant(s)).

warning

Because the scope is captured when the route is saved, a tenant you onboard later is not automatically covered. After adding a new tenant, open each route that should include it, and save it again to refresh the scope.

Channels

Channel	What is sent	Secret field
Webhook	A signed JSON alert payload, POSTed to your endpoint	Signing secret (optional) - used to compute an HMAC-SHA256 signature sent in the X-Surface-Signature header
SOC channel	The same signed JSON payload, aimed at Slack/Teams-style incoming webhook receivers	Signing secret (optional)
On-call (PagerDuty)	A PagerDuty Events API v2 trigger event	PagerDuty routing key (required for an enabled route)

For webhook and SOC channel routes, the JSON body looks like:

{
  "type": "alert",
  "alertId": "d3b7c1e2-...",
  "tenantId": "9f2a44b0-...",
  "alertType": "phishing_detected",
  "severity": "critical",
  "origin": "https://login-example.suspicious.site",
  "description": "Lookalike login page detected",
  "timestamp": "2026-07-08T14:03:22Z"
}

For PagerDuty routes, alert severity is mapped onto PagerDuty's scale (critical stays critical, high becomes error, medium becomes warning, low becomes info), and the alert ID is used as the deduplication key so repeated deliveries of the same alert do not open duplicate incidents.

Verifying webhook signatures

When a route has a Signing secret, every delivery carries an X-Surface-Signature header so your receiver can verify that the payload really came from Surface and was not tampered with in transit:

1. Take the raw request body exactly as received (before any JSON parsing or re-serialization).
2. Compute the HMAC-SHA256 of that body using the shared signing secret as the key.
3. Hex-encode the result and compare it (constant-time) with the X-Surface-Signature header value.

Reject any request whose signature does not match. Requests are sent with Content-Type: application/json.

Destination URL validation

The Target URL is validated before any delivery is attempted:

• It must be a well-formed http:// or https:// URL with a host. Use https:// for anything crossing the public internet - the signing secret protects payload integrity, not confidentiality.
• The destination must resolve to a publicly routable address. Requests to loopback, link-local, cloud-metadata, and other internal or reserved network addresses are refused, and this check is applied at connection time on every delivery.
• If your webhook receiver lives on a private network (common in fully self-hosted deployments), your platform operator can explicitly allow private address ranges in the deployment configuration.

Secrets are write-only

Once saved, a signing secret or PagerDuty routing key is stored encrypted and is never shown again - not in the page, and not in any API response. The route card only shows a Secret configured badge. When editing a route, leave the secret field blank to keep the stored value, or type a new value to replace it.

Using the page

Only an organization owner can create, edit, test, or delete routes; other organization roles can view them.

1. Go to Control > Alert Routing and select New route.
2. Fill in the dialog:

Field	Meaning
Name	A label for the route, e.g. SOC critical feed. Also used to confirm deletion.
Channel	Webhook, SOC channel, or On-call (PagerDuty).
Target URL	The destination endpoint. For PagerDuty this is the Events API URL.
Minimum severity	Low (all alerts), Medium, High, or Critical.
Signing secret / PagerDuty routing key	Optional HMAC signing secret for webhook/SOC channel; required routing key for an enabled on-call route. The label reads "(leave blank to keep current)" when editing.
Enabled	Untick to keep the route configured but inactive.

3. Select Save route.
4. On the route card, select Test to send a synthetic low-severity alert ("This is a test alert routing notification from Surface Security") through the route using the stored secret. The result appears on the card, e.g. "Test alert delivered successfully". Testing works even on disabled routes.

Screenshot

[SCREENSHOT PLACEHOLDER: The "New route" dialog with Channel set to "On-call (PagerDuty)", showing the "PagerDuty routing key" secret field and the Minimum severity dropdown open on "Critical".]

To remove a route, select Delete on its card. The confirmation dialog requires you to type the route's name; once deleted, matching alerts are no longer forwarded.

Worked example: critical alerts from two tenants to a SOC webhook

An MSSP manages two tenants, Northwind Retail and Contoso Health, and wants every critical alert from either tenant to land in the SOC's webhook-driven triage queue.

1. Sign in as an organization owner whose access covers both tenants.
2. Go to Control > Alert Routing and select New route.
3. Enter:
   • Name: SOC critical feed
   • Channel: Webhook
   • Target URL: https://soc.example-mssp.com/hooks/surface
   • Minimum severity: Critical
   • Signing secret: a random shared secret, also configured on the SOC receiver so it can verify the X-Surface-Signature header
   • Enabled: ticked
4. Select Save route. The card now shows Webhook - min severity critical - all alert types - 2 tenant(s) with a Secret configured badge.
5. Select Test and confirm the SOC receiver logs the synthetic alert with a valid signature.

From now on, any critical alert raised in Northwind Retail or Contoso Health is delivered to the SOC endpoint within moments of being created, with the tenantId field telling the SOC which customer it belongs to. Analysts can then open the alert in the organization-wide Alerts view for triage.

Video

[VIDEO PLACEHOLDER: 60-second walkthrough - create the "SOC critical feed" route, test it, then trigger a critical alert in a managed tenant and show it arriving at the webhook receiver.]

Troubleshooting and FAQ

The Test button reports a failure. The message on the card includes the reason - most commonly a non-2xx response from your endpoint, a timeout, or a rejected destination address (private or internal addresses are blocked by default). Fix the endpoint and test again.

A route stopped covering a tenant I recently added. Route scope is captured at save time. Edit the route and save it again to include newly added tenants.

Do failed deliveries retry? No. Delivery is best-effort and failures are visible in the platform's service logs. For guaranteed, replayable event delivery into a SIEM, use per-tenant SIEM integration alongside routing.

Does Test page my on-call rotation? Yes - a test on an On-call (PagerDuty) route sends a real trigger event using the stored routing key, so PagerDuty will open an incident (at its lowest severity). Warn your on-call before testing, or test against a dedicated low-urgency service first.

Can I filter a route by alert type? Each route carries an alert-type filter, shown on the route card ("all alert types" or a list of types). Routes created from this page match all alert types; use the minimum severity to narrow what fires.

Where do routed alerts live in the console? Routing only forwards a copy. The alert itself remains in the owning tenant and in the organization-wide Alerts view for triage, regardless of delivery outcome.

Who receives the audit trail for route changes? Every create, update, and delete is recorded in the organization Audit Log, and also in the audit log of each affected tenant.

Every route change requires the organization owner role; if the buttons are missing, your account has a read-only organization role.