Controls and verification

Beta release

These controls require application integration. Begin with a small owned pilot, review outcomes, and enable each control deliberately.

Independent controls

Control	What it measures	When to enforce
Cloud detection	Automated request evidence	After reviewing observed traffic; enable in SDK and dashboard
Local rules	Your application policy	After validating the rule against authenticated application state
Shared quota	Request admissions per account and optional session	When you need a request allowance across replicas
Concurrency	Simultaneously protected work	When all work, including streaming, is inside the lease lifecycle
Model budget	Reserved and confirmed tokens / configured cost	When every model attempt has conservative bounds and reliable accounting

Shared controls use trusted server identities and stable secret-derived pseudonyms. Do not take an account ID or paid-plan claim directly from browser input. Keep property, rule IDs, secrets, and policy consistent across replicas. Policy changes may require a new rule ID and fresh counters; coordinate them deliberately.

Outages and cancellation

Cloud detection fails open by default: a detector outage lets the request proceed with degraded protection. Local rules and shared controls have separate failure policies; an unavailable cloud detector does not disable an enforced local rule.

Quota, concurrency, and budget controls default to observe/open. Enforced exhaustion denies work; unavailable shared state follows that control’s failure policy. Choosing closed can reject otherwise valid requests when the state service is unavailable. Choosing open prioritizes availability and cannot guarantee a hard cap.

For concurrency, confirmed completion releases capacity. Cancellation, errors, or lease loss can retain capacity until the configured maximum runtime because a disconnected client is not proof the provider stopped. Your handler must honor cancellation and bound upstream execution.

Model budgets and usage

Reserve a conservative maximum before each provider attempt, including retries, fallbacks, and tool-loop model calls. Supply a versioned price catalog and enforce input/output bounds in the application. SDK configuration alone does not constrain the provider.

Confirmed final usage reconciles the reservation. Missing usage, cancellation, or failed settlement retains the reserved maximum. Unknown usage is not zero usage. An overrun can be recorded but cannot reverse an already-billed model call.

The SDKs provide an Ollama final-usage normalizer. Other provider clients require application integration and verification of their final usage fields. Provider pricing, hidden retries, and token estimation affect the accuracy of any budget. These controls do not change your WebDecoy subscription or guarantee a provider invoice amount.

Data and reporting

Admission uses request metadata and local policy results. Prompts and model responses are not needed in detection or usage payloads. Shared identities are pseudonyms and remain correlatable; they are not anonymous. Keep raw application context and credentials out of custom reasons, route names, and logs.

Outcome and model-attempt reports are bounded, best-effort telemetry. An absent report does not prove a model call did not happen. Let completion hooks finish and drain reporting during graceful shutdown; reporting failures must not trigger another model call.

Verify your integration

Use a deterministic fixture or local model first, so validation does not consume paid model credits. For Node.js, the SDK’s doctor commands automate most of this list: doctor-model.mjs covers steps 1 to 3 and 6 for model routes, and doctor-mcp.mjs check covers allowed, forbidden, cross-tenant, cancellation and outage calls for MCP tools. See Install AI Protection. They complement, not replace, a test against your own handler and provider client.

1. Allowed request: authenticate, send a valid request, and confirm the handler runs once and the decision appears in the correct property’s AI Protection page.
2. Denied request: trigger a known local policy denial and verify the model handler never starts. Check the reported application decision.
3. Detector outage: simulate an unavailable detector in a test environment. Verify the configured fail-open behavior and degraded coverage.
4. Shared quota: exhaust an enforced allowance across two application instances. Confirm 429 and retry guidance before inference. Admission recovery does not deduplicate model execution.
5. Concurrency: hold a stream open and attempt another request above the limit. Verify completion releases capacity and disconnect handling follows the lease policy.
6. Budget: exceed an enforced reservation limit and confirm no provider call starts. Separately test confirmed usage, unknown usage, and settlement failure.
7. Dashboard: review allowed/denied decisions, degraded checks, model attempts, and known versus unknown usage. Confirm your application logs agree with the reported outcomes. For an MCP tool call, open ?property=<property ID>&action=<action ID> on the AI Protection page to see every reported phase of that one call.

Test each configured outage policy separately. Do not infer budget or concurrency enforcement from a successful bot-detection test.

SDK references

• Node.js controls and lifecycle
• Go SDK
• Python controls and lifecycle

Alert webhooks

In AI Protection → Alert webhook, an organization owner or administrator can configure one public HTTPS receiver for the selected property. Enter a randomly generated signing secret of 32–128 characters, also stored in your receiver. The URL and secret are encrypted at rest and are not returned by the settings API. Leave either field blank on subsequent saves to retain its value.

Alerts are generated from SDK-reported denials, including local policy rejections and caller pauses. They do not independently prove malicious intent. No SDK upgrade is needed if your integration already reports these outcomes. Missing or failed SDK reports cannot generate alerts. Allowed requests and observe-only findings do not generate denial alerts.

Delivery runs in a backend worker, outside runtime admission. A receiver outage cannot change the protection decision. The dashboard shows the latest 50 deliveries, their status, attempt count and response status. Incident links include the property and request ID; caller-attributed incidents can open the caller timeline. If another property is selected, choose the linked property first. Evidence may be incomplete or no longer retained.

Verify a delivery

Requests carry these headers:

• X-WebDecoy-Delivery: stable UUID across retries; also delivery_id in the body.
• X-WebDecoy-Timestamp: Unix timestamp in seconds for this attempt.
• X-WebDecoy-Signature: v1= followed by a hexadecimal HMAC-SHA256.

Compute the HMAC using your signing secret over timestamp + "." + raw_request_body. Verify the signature using a constant-time comparison before parsing or processing the body. Reject timestamps more than five minutes from your clock. Require the delivery header to match the signed body’s delivery_id, and use that signed value to deduplicate valid requests. Return a 2xx response after you have durably accepted the alert. A crash after acceptance can cause the same delivery to be sent again.

The schema-1 JSON body contains event: "ai_protection.denied", delivery_id, property_id, request_id, timestamp (report receipt time), reason and evidence_url. Tool reports can additionally contain action, policy_version, outcome and a pseudonymous caller. It excludes prompts, tool arguments, model responses, raw authentication identities and credentials.

Delivery limits and configuration changes

• Five attempts maximum, with retry delays of 10 seconds, 1 minute, 5 minutes and 30 minutes. Network failures, HTTP 408/429 and 5xx responses are retryable. Other non-2xx responses fail permanently. Redirects are not followed.
• Up to 1,000 new deliveries per property per rolling 24 hours. Additional evaluated denials increment the dashboard’s capacity-suppressed count.
• A worker restart recovers the durable queue. Report discovery looks back at most 24 hours; an outage beyond that window can leave older reports unalerted. Pending delivery attempts expire after 24 hours.
• Delivery history is retained for 30 days. Polling and backlog mean these are asynchronous alerts, with no instantaneous-delivery guarantee.
• Every settings save creates a new configuration revision, cancels outstanding deliveries and starts alerting on reports received after that save. An HTTP request already sending may still arrive. A blank field preserves its saved value; it does not remove the receiver or secret. Disable alerts to stop new deliveries. Existing plan entitlements for alerts apply.

Caller pauses and provider credentials

A caller pause changes WebDecoy admission for supported, opted-in integrations. Provider session/token revocation is a separate action in your own identity provider. The dashboard does not observe or verify provider credential status. Follow the credential revocation guide to identify the right principal, choose a scoped provider action and verify it at your application boundary.

Saved state and SDK denial feedback

The caller panel separates the saved pause timestamp from a request denial reported by the SDK for that exact pause revision. A matching report shows its server receipt time and request ID. Receipt time is not the moment enforcement began. Resuming or saving another pause creates a new revision, so delayed reports for the previous revision cannot confirm the new control.

Feedback searches the latest 10,000 property reports received in the last seven days. If no matching report exists, confirmation stays unknown. This can mean no new request occurred, reporting failed, the evidence fell outside the sample, or the installed SDK does not report revisions. Node SDK alpha.15 adds revision evidence; older SDKs continue enforcing pauses without that evidence.

A reported denial establishes what one SDK reported. It does not verify all replicas, cancel work already running, prove malicious intent, or revoke provider credentials. Historical denial feedback can remain visible after a pause expires; the separate active-state label shows whether the pause is currently effective at the last refresh. Refresh the caller panel to retrieve new evidence. Caller-control outages continue to fail open.

Multiple instances, restarts and outages

Each opted-in Node instance reads caller pause state on its next successful control check. There is no pause decision cache to invalidate. Instances using the same property and stable subject secret derive the same caller pseudonym; a restarted instance checks the current state before admitting new work.

There is no finite enforcement deadline across disconnected instances. During an outage or timeout, caller checks deliberately allow work to continue with an unavailable result. Application authorization still applies. When connectivity returns, the next successful check uses current pause state. Idle instances cannot produce denial evidence until another request arrives. Work admitted before the pause can finish.

The default caller-check deadline is 1000 ms, configurable with callerPauseTimeoutMs (1–10000 ms). This is a request timeout, not a promise that all instances have applied a pause. Event-loop delays can also postpone timeout handling. Reporting failure does not cancel application work; missing reports leave dashboard confirmation unknown.

Provider action records

Owners/admins can append a structured provider observation from the caller panel: provider, credential scope, reported result and observation time. Each record retains the operator and save time. The latest 20 records are shown; corrections append to history. Pauses and provider records remain independent.

These are operator reports, not live credential verification. No provider call is made and no credentials or free-form evidence are collected. Follow the recording guide after checking the caller mapping and the result in your own provider/application.

Per-tool pauses (Node alpha.16)

Enable sharedRuntime.toolPause: true in your Node action/MCP integration. MCP supplies server/tool metadata automatically. Plain action integrations must provide toolSchema for every action. Tool-only checks do not require caller reporting. When caller pauses are also enabled, both checks share one request; callerPauseTimeoutMs controls its deadline (default 1000 ms).

In AI Protection → Tool pauses, choose a saved control or enter the exact server ID and tool name. You can also use Manage tool pause in discovered tools. Review the property, server/tool and all-caller scope, then enter a reason, choose an expiry and confirm. Only organization owners/admins can save changes. Resume uses the same review and audit flow. Saved controls remain listed even if the tool disappears from the sampled inventory. There are at most 1,000 saved tool controls per property.

A pause covers that exact server/tool name on the selected property, across all callers and input-schema versions. Other server/tool names remain available. Changing the server or tool name changes its control identity; review controls before renaming. A tool remains discoverable while paused. Unwrapped tools and SDKs without the opt-in are not covered.

Each successful online check reads current state before shared limits and action execution. Already-admitted/running work can finish. Outages, timeouts and malformed responses fail open with unavailable evidence; application permissions still apply. Caller denial takes precedence when both caller and tool deny.

The dashboard separates saved state from an SDK-reported denial for that exact tool-pause revision. Feedback includes receipt time/request ID and searches the latest 10,000 property reports within seven days. Missing evidence stays unknown; resuming or saving a new revision cannot inherit a previous revision’s report. This is not acknowledgment from all instances, provider credential revocation, or independent verification of execution. No model calls or tool arguments are needed to check a pause.