Skip to main content

Pro Tier Integrations

note

API paths that contain tenant keep that word for compatibility. In the product it means your workspace.

The Pro tier adds team workflows, webhook automation, and audit exports so your SOC or compliance team can integrate Dralvia with downstream systems. If a term is unfamiliar, open the Glossary.

What you get​

CapabilityDescriptionWhere to manage
Teams & membersOrganize responders, assign owners, and map roles to your SSO identity system.Pro Tier Console (#/pro-tier)
WebhooksSubscribe to report.generated, audit.export.ready, saas.lifecycle.stuck, and email.verdict events (Slack/Teams or generic JSON).Pro Tier Console (#/pro-tier)
Audit exportsGenerate JSON exports for scans and reports.Pro Tier Console (#/pro-tier)

Access requirements​

  • Signed-in workspace session is required for the console and API routes.
  • License must be active for your workspace.
  • Pro entitlements must be present on your license; otherwise the API returns pro_tier_required.
  • Dralvia support can assist if your workspace context or entitlement is not visible.

Route layout​

#/pro-tier now opens on Overview first, then separates work into:

  • Teams for responder groups and membership changes
  • Webhooks for outbound event automation
  • Exports for audit artifact generation and replay/download actions

This keeps the current plan posture readable without mixing team, webhook, and export controls into one continuous page.

Teams & members​

  1. Open Pro Tier Console.
  2. Create a team with a name + description.
  3. Add members by email and role (owner, member, or viewer).
  4. Remove members or delete teams when they are no longer needed.

Teams are workspace-scoped and never visible across workspaces.

Webhooks​

  1. Open Pro Tier Console.
  2. Add a webhook URL, event list (comma-separated), and an optional signing secret.
  3. Use Send test to validate delivery and Delete to remove old hooks.
  4. Use your webhook endpoint to ingest notifications.

Slack and Microsoft Teams​

Paste a Slack incoming webhook URL (https://hooks.slack.com/...) or a Microsoft Teams connector URL (https://...webhook.office.com/...) as the webhook URL and Dralvia posts a readable alert (event plus the key fields like verdict and risk) straight into that channel. No extra setup: the destination is detected from the URL. Any other URL receives the signed JSON envelope below, so your own systems keep working unchanged. (Slack and Teams ignore the signing secret; it applies only to generic JSON endpoints.)

Supported events​

EventFires whenPayload highlights
report.generatedA scheduled or on-demand report finishes generation for your workspace.report_id, report_type, download_url
audit.export.readyA Pro audit export job reaches the ready state.export_id, include, download_url
saas.lifecycle.stuckA SaaS governance record has sat in discovered or reviewing past the per-workspace lifecycle SLA. Driven by the periodic SaaS lifecycle stuck-in-state sweeper (see Browser Protection).app_id, lifecycle_state, lifecycle_state_changed_at, stale_for_days, threshold_days, owner, review_status
email.verdictEmail Protection scored an inbound message as risky (Caution or Avoid). Clean (Safe) messages do not fire, so a Slack or Teams channel is not flooded.verdict, risk_level, risk_score, subject, sender, message_id, reasons, trace_id

Subscribe by listing the event names (comma-separated) when you create a webhook. Each delivery is one event_type per HTTP POST and carries the same envelope:

{
  "event": "saas.lifecycle.stuck",
  "tenant_id": "<your workspace>",
  "payload": { "app_id": "...", "lifecycle_state": "reviewing", "stale_for_days": 30 }
}

Delivery details​

  • HTTP POST with Content-Type: application/json.
  • X-Dralvia-Event header repeats the event name for routing.
  • When a signing secret is configured, the body is signed with HMAC SHA-256 and the digest is delivered in X-Dralvia-Signature. Validate the signature before processing.
  • A 5-second connect/read timeout applies. Non-2xx responses are recorded in last_error (visible in the Pro Tier Console) and the next sweep retries; the same (workspace, app_id, lifecycle_state) will not re-page until the app advances out of the monitored state and re-enters it.
  • The dispatcher de-duplicates saas.lifecycle.stuck per (tenant_id, app_id, lifecycle_state) so a single stuck app pages once per state until it transitions or the policy is widened.
  • When the per-workspace policy sets escalation_after_sweeps > 0 (default 3), the sweeper auto-opens a TicketBridge ticket once it has observed the same stuck triple that many times in a row. The ticket carries the SaaS app id as a domain artifact, the SLA breach context in risk.reasons, and a human-readable summary in the user_note. Each triple escalates exactly once until it transitions out of the monitored states.
  • Per-workspace SLA thresholds for saas.lifecycle.stuck come from GET|POST /swg/saas/governance/lifecycle/policy (default 14 days for both discovered and reviewing, clamped [1, 365]). Workspace admins can edit the thresholds inline from the Browser Protection KPI strip without leaving the UI.

Triggering the SaaS lifecycle sweeper​

The sweeper that fires saas.lifecycle.stuck is on-demand. Drive it from your own scheduler (cloud scheduler, Lambda timer, GitHub Actions cron, etc.) by calling:

POST https://dralvia.tech/api/tenant/swg/saas/governance/lifecycle/sweep-stuck
Authorization: Api-Key <workspace API key>

The endpoint requires the lifecycle admin role (tenant_admin or tenant_owner). Each call evaluates your governance records once, fires saas.lifecycle.stuck for any newly stale apps, and returns a JSON report with the per-app results.

The sweeper is idempotent within a window: if your timer fires every hour but the SLA is 14 days, the second hour fires zero events because Dralvia remembers the previous send and only pages once per stuck (app_id, lifecycle_state) pair until the app advances out of discovered/reviewing.

Audit exports​

  1. Open Pro Tier Console.
  2. Choose include values (comma-separated, e.g. scans,reports).
  3. Optionally set since_days to limit the time window.
  4. Download the job payload once the job is complete (Console → Download, or GET /pro/audit/exports/<id>/download).

Exports are stored under your workspace storage root (see EvidencePack (Dralvia's exportable evidence report) storage guidance).

API endpoints​

All endpoints require an active signed-in workspace session or workspace API key, plus an active license.

  • GET /pro/teams
  • POST /pro/teams
  • POST /pro/teams/<id>/members
  • DELETE /pro/teams/<id>/members
  • GET /pro/webhooks
  • POST /pro/webhooks
  • POST /pro/webhooks/<id>/test
  • DELETE /pro/webhooks/<id>
  • POST /swg/saas/governance/lifecycle/sweep-stuck (run the SaaS lifecycle stuck-in-state sweeper; lifecycle admin role required)
  • GET|POST /swg/saas/governance/lifecycle/policy (per-workspace SLA thresholds that drive saas.lifecycle.stuck)
  • GET /pro/audit/exports
  • POST /pro/audit/exports
  • GET /pro/audit/exports/<id>
  • GET /pro/audit/exports/<id>/download

Operational notes​

  • Webhook delivery failures are retried automatically; monitor last_error in the console.
  • Keep webhook endpoints restricted to HTTPS and validate the HMAC signature.
  • Audit exports are immutable artifacts; store them in your compliance evidence system.

Who this is for​

This guide is for workspace owners, workspace admins, and security operators who need clear, repeatable steps without support intervention for day-to-day execution.

Role-based start here​

  • Workspace Owner: Start with Before you start, then complete Step-by-step and Known limits and rate limits.
  • Workspace Admin: Focus on Step-by-step, What each button does, and API and automation.
  • Security Analyst: Start at Day-2 operations and Troubleshooting, then use API error quick reference.
  • Integrator/Engineer: Start at API and automation, then validate with Step-by-step and FAQ.

Before you start​

Use this short checklist before making changes:

  1. Confirm you are signed into the correct workspace account.
  2. Confirm your role includes the permissions needed for this page.
  3. Confirm your browser session is fresh (if pages behave unexpectedly, sign out/in once).
  4. Confirm required prerequisites (API keys, agent enrollment, license, upstream integrations) are already in place.

Step-by-step​

Follow this sequence for predictable results:

  1. Open the workspace from the workspace menu.
  2. Review current status/health/last update indicators before making changes.
  3. Apply one change at a time and save.
  4. Run the available validate/probe/refresh action.
  5. Confirm the expected output appears (status change, new event, successful result).
  6. If behavior is not as expected, use Troubleshooting below before repeating actions.

Day-2 operations​

After initial setup, keep this surface healthy with a simple routine:

  1. Daily: verify data freshness and error banners.
  2. Weekly: review trends, limits, and failed actions.
  3. Monthly: review permissions, keys/tokens, and stale entities.
  4. After any incident: capture evidence and update your internal operating notes.

What each button does​

Button labels can vary by module, but behavior is consistent:

  • Refresh: reloads the latest data from backend APIs without changing configuration.
  • Save: persists workspace-scoped configuration changes.
  • Run/Probe/Validate: executes a non-destructive health or verification action.
  • Download: fetches workspace-scoped artifact(s) (for example bundle, checksum, signature, or report).
  • Verify: checks integrity/consistency and returns pass/fail details.
  • Enable/Disable: toggles module behavior for your workspace; audit evidence should be recorded.

If a button appears disabled, check role permissions, required fields, and workspace license/feature entitlement first.

Self-check playbook​

Use this 5-step isolation flow before escalating:

  1. Configuration: confirm required inputs are present and formatted correctly.
  2. Permission: confirm your role can perform the action (401/403 usually indicates authz/authn mismatch).
  3. License/feature: confirm the feature is enabled for your workspace plan and module toggles.
  4. Quota/rate limit: check for 429 responses and cooldown windows.
  5. Service health: if you see 5xx, retry once after 30-60 seconds and capture exact error text.

If still failing, escalate with workspace ID, UTC timestamp, route, action, payload shape (no secrets), and screenshot/error response.

Troubleshooting​

Use this quick triage order to reduce time-to-fix:

  1. Auth/session: refresh token by signing out/in.
  2. Workspace context: confirm you are in the correct workspace.
  3. Inputs/config: verify required fields and formats.
  4. Quota/license: confirm limits and feature entitlement.
  5. Service health: retry after short delay if backend is transiently degraded.

For escalation, include workspace ID, timestamp (UTC), route name, action attempted, and full error message.

API and automation​

Everything in this page should remain workspace-scoped. If your team prefers automation, use the corresponding API endpoints with the same guardrails as the UI:

  • Use authenticated requests bound to your workspace context.
  • Use idempotency/retry controls where available.
  • Validate outcomes in the UI after automated runs.

If your endpoint mapping is not obvious, start from Help Center and follow the linked API docs.

Next best actions​

After finishing this page, continue with related workflows so your workspace setup stays end-to-end complete:

FAQ​

Q: I clicked save but nothing changed. A: Refresh once, confirm permissions, and verify required fields.

Q: Why do I see missing API key/unauthorized errors? A: Confirm your workspace API key/session is valid and mapped to the correct workspace scope.

Q: Can non-admin users use this page? A: Usually read-only access is possible; write actions require workspace-admin or equivalent roles.

Next steps​

After finishing this guide:

  1. Validate the result in the related dashboard/workspace.
  2. Export or capture evidence if this affects compliance/incident operations.
  3. Share the same runbook internally so other operators follow identical steps.
  4. Return to Help Center for adjacent workflows.

API error quick reference​

Use this matrix when a UI action fails with an HTTP/API error.

ErrorMeaningWhat to do now
401 UnauthorizedSession token is missing/expired or request is not authenticated.Sign out/in, refresh once, then retry. Confirm your session is active in the correct workspace.
403 ForbiddenYou are authenticated but your role is not allowed to perform this action.Confirm your role includes the required permission for this button/action. Ask a workspace admin to grant access.
404 Not FoundThe route/resource does not exist in current workspace context (or feature not enabled).Confirm URL/route, workspace context, and feature availability. Refresh and retry; if persistent, capture timestamp and route and contact support.
429 Too Many RequestsRate limit/quota window was exceeded.Wait for cooldown/reset window, retry once, then reduce burst traffic/backoff if automated.
500 Internal Server ErrorBackend failed unexpectedly while processing the request.Retry after 30-60 seconds. If still failing, escalate with workspace ID, UTC time, route, action, and full error text.

Known limits and rate limits​

These limits can vary by plan and feature, but behavior is consistent:

  • Burst traffic can trigger 429 Too Many Requests.
  • Workspace quotas apply per feature/module and reset on configured windows.
  • Repeated retries without backoff can extend recovery time during saturation.

Recommended operator behavior:

  1. Retry once after cooldown for 429 responses.
  2. Use exponential backoff in automation.
  3. Monitor usage/quota dashboards for sustained high utilization.
  4. Request quota review when normal workload regularly approaches limits.