Skip to main content

TicketBridge & Case Management

If a term is unfamiliar, open the Glossary.

TicketBridge is Dralvia’s built-in case pipeline. Use it to send EvidencePacks (Dralvia's exportable evidence reports), track analyst actions, and sync decisions back to your helpdesk.

Workspace route structure:

  • #/escalations opens on Overview for awareness and queue posture.
  • Queue holds filters, ticket review, comments, and EvidencePack downloads.
  • Queue also lets signed-in users close their own open tickets.
  • Create holds manual escalation submission so new-ticket work stays separate from queue triage.

Creating tickets​

From the UI​

  • On any scan or alert detail view, click Send to Security.
  • Choose severity, assignee, and optional notes; the EvidencePack ID and artifacts attach automatically.

Via API​

curl -X POST "$BASE_URL/<ticketbridge-create-endpoint>" \
  -H "X-API-KEY: $DRALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "tenant_id": "tenant-alpha",
        "artifact_type": "domain",
        "artifact_value": "bad.example",
        "risk_score": 82,
        "risk_reason": "Brand impersonation + malware",
        "evidencepack_id": "pack_abc123"
      }'

The response includes a ticket ID you can use to query status or update decisions.

Workspace-scoped credentials may also POST to the internal ticket endpoint. That path is kept for older clients and forwards the request to the same workspace escalation flow the UI uses, so the ticket is created identically either way. New integrations should call the workspace escalation endpoint directly.

Fixed on 2026-08-11

That compatibility path returned 500 Internal Server Error instead of forwarding. A workspace-scoped client POSTing to the internal ticket endpoint got a server error and no ticket; the workspace escalation endpoint and the UI were unaffected throughout. If an older integration silently stopped raising tickets, this was why. No client change is needed.

Working a ticket​

  • Use #/escalations to view your workspace queue by status.
  • Click a ticket to see the EvidencePack summary, risk reasons, and history.
  • Add analyst notes, change status, or push the case to your downstream case-management system if integrations are enabled.
  • Ticket queues and per-ticket comment threads now paginate at 3 items per page in the console.
  • Opening Queue, creating a ticket, and opening comments keep the current browser session stable instead of repeatedly reloading the queue.
  • Use Close ticket when your team no longer needs analyst follow-up. Closing is scoped to your workspace, records a closure timestamp, adds a short close comment, and refreshes the queue.

Workspace users manage tickets from #/escalations.

Closing from the workspace API​

Signed-in browser sessions can close a visible TicketBridge case:

curl -X POST "$BASE_URL/portal/escalations/<ticket_id>/close" \
  -H "Authorization: Bearer $DRALVIA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Resolved in our incident tracker."}'

The response returns the safe ticket payload with status: "closed" and closed_at. Closing does not create a Safe/Malicious decision; it only closes the workflow item. Tickets outside the signed-in workspace return 404.

Routing and escalation ownership​

Every escalation is routed when it is created, so it lands with the right responder group instead of a single shared queue.

  • Routing looks at the artifact type, your plan, and the risk score, then assigns the matching handling queue and an escalation owner.
  • The escalation owner is the responder group accountable for your case until a decision is made. It appears as owner on the ticket payload and in the ticket history your downstream system receives.
  • If no specific rule applies, the case goes to the default queue with the default owner, so nothing is ever left unowned.
  • You do not need to configure anything for this. Routing rules are managed by Dralvia based on your plan and module setup. If your team wants a dedicated routing rule (for example, all repository escalations to a named group), contact support.

SLA proof and status history​

Every case keeps a durable status timeline and a per-case SLA record, so you can verify how fast your escalations were handled instead of trusting a summary.

Status history​

curl "$BASE_URL/portal/escalations/<ticket_id>/history" \
  -H "Authorization: Bearer $DRALVIA_SESSION_TOKEN"

The response lists every status transition with the time it happened and who drove it by role (system, internal, or tenant):

{
  "ticket_id": "abc123",
  "status": "malicious",
  "status_history": [
    {"from_status": null, "to_status": "queued", "actor_role": "system", "created_at": "2026-07-01T10:00:00+00:00", "derived": false},
    {"from_status": "queued", "to_status": "malicious", "actor_role": "internal", "created_at": "2026-07-01T10:24:00+00:00", "derived": false}
  ],
  "sla": {
    "first_response": {"actual_seconds": 1440, "target_minutes": 60, "met": true},
    "decision": {"actual_seconds": 1440, "target_minutes": 240, "met": true},
    "close": {"actual_seconds": null, "target_minutes": null, "met": null}
  }
}
  • Cases created before timeline tracking show derived: true entries reconstructed from their lifecycle timestamps, so older cases still have an honest history.
  • Tickets outside your workspace return 404.

Reading the SLA block​

  • actual_seconds is the measured time from case creation to that stage.
  • target_minutes is the service target that applies to your workspace. When no target is configured for a stage, it is null and met is null: Dralvia does not report a pass without a real target.
  • met is an explicit true/false verdict you can cite in reviews and compliance evidence.

Case reports tied to EvidencePack​

Every escalation can be exported as a ready-to-share report that carries its own verification anchors, so the recipient can check the evidence is intact without trusting the messenger.

curl "$BASE_URL/portal/escalations/<ticket_id>/report?template=incident_summary" \
  -H "Authorization: Bearer $DRALVIA_SESSION_TOKEN"

Two templates are available:

  • incident_summary is written for management and compliance reviews: what happened, the verdict, the full status timeline, the SLA record, and the EvidencePack trust receipt.
  • escalation_handoff is written for responders and MSP handoffs: it additionally lists the exact risk reasons that triggered the escalation.

The response contains the structured data (case, status_history, sla, evidence) plus a rendered markdown field you can paste directly into your incident tracker, a customer email, or an audit bundle.

The evidence.trust_receipt block is the same portable receipt used across Dralvia: it carries the EvidencePack merkle root and integrity verdicts, so anyone holding the pack can recompute the root and confirm nothing was altered. No account or secret is needed to verify it. If a case has no EvidencePack, the report says so honestly instead of omitting the section.

An unknown template value returns 400 with the list of allowed templates. Reports are workspace-scoped: tickets outside your workspace return 404.

Integrations​

  • TicketBridge can sync with customer case-management tools via webhook. Ask support to enable webhook callbacks and exchange a shared secret for your workspace.
  • You can also export tickets as CSV for weekly reviews or compliance evidence.

Webhook examples for common systems​

Your helpdesk or SOAR tool can push analyst outcomes back into Dralvia through two signed callbacks:

  • POST /webhooks/ticketbridge/tickets/<ticket_id>/decision records a decision (safe, malicious, or need_info).
  • POST /webhooks/ticketbridge/tickets/<ticket_id>/comments appends an external comment to the case thread.

Both require an HMAC signature: the hex SHA-256 HMAC of the exact raw request body, computed with the shared secret you exchanged with support. Send it in the X-TicketBridge-Signature header (the X-Dralvia-Signature and X-Hub-Signature-256 header names are also accepted, with or without a sha256= prefix).

Generic signed decision callback (curl)​

BODY='{"decision":"malicious","notes":"Confirmed credential phishing.","analyst":"soc-tier2"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
curl -X POST "$BASE_URL/webhooks/ticketbridge/tickets/<ticket_id>/decision" \
  -H "Content-Type: application/json" \
  -H "X-TicketBridge-Signature: sha256=$SIG" \
  -d "$BODY"

Generic signed comment callback (curl)​

BODY='{"message":"Ticket triaged in our helpdesk, blocking at the proxy.","actor_email":"[email protected]","actor_role":"external"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
curl -X POST "$BASE_URL/webhooks/ticketbridge/tickets/<ticket_id>/comments" \
  -H "Content-Type: application/json" \
  -H "X-TicketBridge-Signature: sha256=$SIG" \
  -d "$BODY"

GitLab​

If your cases land as GitLab issues, add a small automation job (for example a scheduled or label-triggered CI job) that posts the decision when an issue is labeled resolved::malicious or resolved::safe. GitLab webhook payloads include the issue labels; your receiver script extracts the Dralvia ticket ID from the issue description (it is included as TicketBridge ID) and runs the signed curl above.

Zammad​

Use a Zammad trigger on state change to call a small relay script (webhook target) that signs the body and forwards it. Zammad's built-in outbound webhook cannot compute an HMAC of a custom body, so route it through your automation runner (n8n, StackStorm, a 10-line Flask/Lambda relay) that reads the shared secret and performs the signed POST.

Jira, ServiceNow, and similar​

Both support outbound automation steps (Jira Automation "Send web request", ServiceNow Flow Designer/Business Rule with a script step). Compute the signature in a script step (standard HMAC-SHA256 libraries are available in both platforms), then send the decision callback when your incident is closed with a verdict field.

Troubleshooting signatures​

  • The signature must cover the exact raw body bytes you send. Recompute after any reformatting; even a changed space breaks it.
  • 503 webhook_not_configured means callbacks are not enabled for the service yet: contact support.
  • 401 signature_required means the header is missing; 403 invalid_signature means the secret or body does not match.
  • During secret rotation both the old and new secret are accepted, so you can switch without downtime.
  • Callbacks are rate limited to 60 requests per minute per endpoint.

Decisions & automation​

  • When you mark a ticket as Approved or Blocked, the system can trigger follow-on actions (e.g., block via SWG or safe-link, update a watchlist).
  • Use the workspace TicketBridge status-update API to change status programmatically from your SOC automation playbooks.

Feedback loop (how your decisions help)​

  • Analyst decisions (Safe/Malicious/Need Info) are streamed into Dralvia’s training corpus to reduce false positives and tune detections.
  • You do not need to export anything. The sync happens automatically.
  • If you include notes, keep them focused on security context (avoid personal data).

Awareness metrics​

  • Your SOC lead can track submissions, false positives, and time‑to‑decision using the Awareness Dashboard in My Escalations.
  • Successful manual submission now returns the operator to Queue while keeping the created ticket ID visible.
  • CSV export is available for quarterly reviews once enabled for your workspace.

Who raised a ticket, and your team KPIs​

Every escalation records the workspace it came from and the account that opened it, so a ticket is never anonymous.

On each ticket (Queue tab in My Escalations):

  • Workspace: the name of your workspace as it appears in Dralvia.
  • Opened by: the signed-in account that raised the escalation, plus their department when your directory supplies one. Escalations sent from the browser extension without a signed-in account are labelled as such rather than being attributed to the wrong person.

Your team (Overview tab in My Escalations) turns the same data into per-person KPIs for the window you select:

ColumnWhat it tells you
PersonThe account that raised the escalations (or the browser extension, when no account signed in).
ReportedHow many escalations that person raised in the window.
Confirmed threatsHow many of their escalations an analyst decided were malicious.
SafeHow many were decided safe. Useful for spotting over-reporting or a noisy alert source.
OpenEscalations of theirs still awaiting a decision.
Avg first replyAverage time from their escalation to the first analyst reply.

Why use it: it shows which teams and people are actually reporting, whose reports turn out to be real threats, and where your response times are slow. Security awareness training usually targets the people who never report; this table names them by absence.

The same numbers are on the API, so you can chart them yourself:

curl -sS "https://dralvia.tech/api/portal/awareness?window_days=30" \
  -H "Authorization: Bearer $DRALVIA_TOKEN" | jq '.by_member'

Each entry carries user_email, department, reported, open, closed, decisions (malicious / safe / need_info), confirmed_threats, and avg_first_response_seconds (null when nobody has replied yet).

Limitations: the breakdown only counts escalations raised inside the window you select, it groups every unauthenticated extension report under a single "no account" row, and department is blank unless your identity provider sends it.

Tips​

  • Always include context in notes (user reports, business impact) so future reviewers understand why a decision was made.
  • Link TicketBridge IDs in your incident tracker to maintain a single chain of custody.
  • Export quarterly stats to demonstrate detection/resolution metrics to stakeholders.

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.
  • Close ticket: closes an open TicketBridge item for the signed-in workspace and refreshes the queue.
  • 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.

Q: A decision sent from our helpdesk is not showing on the case. A: Check the webhook response code first: 401 means the signature header is missing, 403 means the secret or the signed body does not match (most often the body was reformatted after signing), and 404 means the ticket ID is wrong. See the webhook examples in Integrations for a working signature recipe.

Q: How do I prove how fast a case was handled? A: Open the case history (/portal/escalations/<ticket_id>/history) for the status timeline and the SLA record, or export a case report (/portal/escalations/<ticket_id>/report) to share the same facts with the EvidencePack trust receipt attached.

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 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.