Hand findings to your ticket system
Send compliance findings to Jira, ServiceNow or any queue through a signed webhook, and write the ticket reference back.
- Version: 0.4
- Feature: integrations.siem
- Role: admin_user
- Type: task
A finding is a person saying that a detection matters and naming who owns it. This handoff puts that sentence where it belongs — your existing ticket queue — over one generic signed webhook, and takes the ticket reference back.
What do I need?
- Licence
- Enterprise
- Role
admin_user
Prerequisites
- An HTTPS endpoint that accepts a JSON batch: your ITSM's own webhook receiver, an automation rule, or the middleware you already run in front of it.
- A dashboard base URL configured under Settings → SIEM Export, if you want tickets to link back to CID222.
- Somebody who can write the receiver's field mapping — CID222 sends a finding, not a ticket.
- A shared secret, or a header token, so the receiver can tell your appliance from anything else that finds the URL.
What this is, and what it is not
CID222 ships no Jira client and no ServiceNow client, deliberately. Every organisation with a ticket system already has a middleware, an automation rule or a webhook receiver in front of it, and that layer is where the field mapping, the project routing and the credentials already live. A first-party vendor client would be a second place to configure all three, a second place for them to go stale, and a per-vendor authentication story to own forever.
So the contract is one shape: a finding, in the same batch envelope and under the same signature as the SIEM webhook, so a receiver written for one parses the other.
Note
Three event types are sent — a finding created, updated and closed — and each is derived from the row's own state rather than from what this destination has already seen. A destination attached after a finding was opened sees its next edit as an update, never a creation. That is honest: it never saw the creation, and it beats replaying six months of findings into somebody's queue on the day it is configured.
Configure the handoff
Open the export settings
Select Settings → SIEM Export and scroll to the ITSM handoff section below the SIEM destination list.
It is a section rather than a page of its own because both answer the same question — where this gateway sends things — and both read the dashboard base URL above them.
Name and address it
Set Name, then Webhook URL to your receiver.
Only a 2xx counts as delivered. Anything else holds the cursor and the batch is retried.
Let the receiver prove it is you
Set Signing secret to have each batch signed, and Custom headers for a receiver that
authenticates with a token instead — one Name: value per line.
Header values are stored encrypted and never returned. The page shows which header names are configured so you can see that an authorization header exists without being handed the token back. Leaving the field untouched on an edit keeps what is stored; clearing it explicitly removes it.
Set the routing defaults
Fill in Project / queue key, Issue type, Priority and Default assignee if your receiver wants them.
CID222 attaches no meaning to these. They ride along in the payload untouched, so the receiver need not hard-code routing.
Enable and test
Switch Enabled on, save, and use the destination's test action.
The test sends a synthetic finding in the real payload shape, not a generic ping — a test that proved the connection but not the payload would be a test of the wrong thing.
The payload
One event per state change, inside the standard batch envelope:
Two fields do the work in a receiver:
correlation_idis stable for the life of the finding. Thread every update onto one ticket with it.event_idis a hash of the finding's state, so a retry of an unchanged row produces a byte-identical payload. Deduplicate on it — but within one destination, not across several, because two destinations receiving the same state legitimately send the same id.
Metadata only, with one honest exception. A finding is derived from the decision record, so
it carries entity types and counts and never a matched value. The exception is next_step: it is
operator free text and is forwarded verbatim. The gateway never writes a detected value into it,
but a human typing one into it will send it. An organisation that cannot accept that should not
attach an ITSM destination.
Write the ticket reference back
CID222 does not learn the ticket id at handoff time, because that would mean blocking the export on your ITSM's response and speaking its API well enough to parse one.
Instead, your receiver — or a person with the ticket open — writes three values back onto the finding through the ordinary findings endpoint: the reference id, the reference URL and the reference status. The Findings tab then shows a Ticket column with three distinguishable states: a link when a URL is known, the bare reference when only an id came back, and Sent when the handoff happened but nothing has returned.
The reference status is never mapped onto the finding's own status. The finding's status is what CID222 recorded a person deciding; letting a remote workflow transition rewrite it would let your ticket system edit a compliance record.
Writing a reference emits one further update event carrying it, which confirms to the receiver that the link landed. It terminates there — the confirming event changes nothing that would produce another.
Verify
- The test finding arrives at your receiver in the shape above, and its signature validates against the secret you set.
- Open a real finding on the Findings tab of the compliance page. Within a poll interval the receiver gets a creation event whose correlation id matches.
- Edit that finding. The receiver gets an update event with the same correlation id and a different event id.
- Write a ticket reference back and confirm the Ticket column changes from Sent to a link.
- Point the destination at a closed port and confirm the appliance raises a
SIEM_EXPORT_DEGRADEDevent with an ITSM-prefixed reason. It is the same event type the SIEM export uses, deliberately: a destination that cannot deliver also cannot deliver the news that it cannot deliver, so the announcement travels out through a healthy SIEM destination instead.
If it fails
- Nothing arrives, and the destination looks healthy — a cycle with nothing to send counts as a success. On a quiet appliance a dead destination is announced when work arrives for it, not before.
- Every finding arrives as an update, never a creation — the destination was attached after those findings existed. This is by design; there is no backfill.
- The receiver sees duplicates — delivery is at least once, and a batch that timed out after your receiver committed it arrives again. Deduplicate on the event id.
- Your reconciliation reports a gap in the sequence numbers — it should not. A batch that never reached the receiver rolls its numbers back, so duplicates are possible and gaps are not. A real gap means events were filtered by a scope, not lost.
- A reference URL is refused — only an absolute
httporhttpsURL is accepted, because the findings table renders it as a link and a remote system writes it. - Findings from another department arrive — the destination has no scope set. An unscoped destination sees every department.
What is planned
Stated plainly, because the surrounding design documents describe more than ships:
- There is no approval workflow. A finding is a record, not a state machine: nothing sends a high-risk event to an approver and takes back an approved or rejected verdict. The extension's dashboard reports an empty approvals list for exactly this reason, rather than inventing rows.
- Nothing polls your ticket system. Status only moves in the direction described above, written back onto the finding.
- There is no per-vendor connector, and none is planned. The generic webhook is the design, not a placeholder for one.
Next steps
- Export detections to your SIEM — the other outbound channel, and the source of the shared delivery and health machinery this one reuses.
- Integrations — the settings page, field by field.
Last updated on