Censusby Steward IT

Documentation › Administration

Integrations: webhooks, syslog and Splunk

Census can send what happens to other tools as it happens: a chat channel learns about new devices, an automation flow opens a change when a ticket comes in, your SIEM records every console sign-in. Set this up under Configuration › Integrations (administrators).

Each destination is one of:

Type For Format
Webhook Chat channels (Slack, Microsoft Teams, Mattermost, Google Chat), automation (Power Automate, n8n, Zapier, Make), your own scripts Census JSON, a Slack-style message, or a Teams card
Syslog SIEMs: Microsoft Sentinel, QRadar, ArcSight, Graylog, Wazuh, Elastic, rsyslog/syslog-ng CEF or JSON, over UDP, TCP or TLS
Splunk HEC Splunk Enterprise and Splunk Cloud Splunk HTTP Event Collector JSON

Events#

Tick the events each destination receives:

Event Type in messages What it is
New assets asset.created A device was found or added for the first time
Asset changes asset.changed Anything on an asset's history: hardware, OS, IP, software installed/updated/removed, user, status, relations
Alerts alert Every alert your alert rules raise, also when nobody gets an email
Console sign-ins audit.signin Sign-ins, sign-outs and failed sign-ins to the console
Console changes audit.change Every change made in the console or through the REST API, as in the audit log (passwords and other secrets are never included)
New tickets ticket.created Help desk tickets from the portal, email, technicians or the API
Ticket updates ticket.updated Replies, internal notes and status changes on tickets (public says whether the requester sees it)

Delivery: events arrive within about 15 seconds. Census keeps its place per destination: if a receiver is down or answers with an error, Census tries again (after 30 seconds, then doubling up to every 30 minutes) and then sends everything it missed, in order, so nothing is lost and nothing is sent twice. A destination that was unreachable for more than 7 days skips ahead. Restarting Census doesn't lose events either. A new destination, and an event type you tick later, start from that moment; earlier history isn't sent.

The list shows each destination's state: working, failing (with the receiver's answer and the next try), off, or waiting (nothing sent yet). Saving a destination makes it try again at once. Send a test delivers a test message with the settings in the form before you save.

Links in messages point to the record in Census (asset, ticket, audit log). They use the Server URL under Configuration › General settings; while it's empty, messages have no links.

Webhooks#

Paste the URL the receiving service gave you and pick the format.

  • Slack, Mattermost, Google Chat: create an incoming webhook for the channel and paste its URL. Messages show the title, a short detail line and an Open in Census link.
  • Microsoft Teams: the old Office 365 connectors are retired. In the channel, choose Workflows › Post to a channel when a webhook request is received, finish the flow and paste the URL it shows. Census sends an Adaptive Card.
  • Census JSON: for automation tools and your own code. Every event is one POST with Content-Type: application/json:
{
  "id": "ticket.created:4f1c2a…",
  "type": "ticket.created",
  "time": "2026-10-10T14:03:11Z",
  "severity": 8,
  "title": "New ticket #1042: VPN down",
  "data": { "ticket": { "id": "4f1c2a…", "number": 1042, "subject": "VPN down", "status": "open",
            "priority": "urgent", "category": "Network", "requester": "Dana Smith",
            "requester_email": "dana@corp.example", "source": "portal", "assignee": "" } },
  "url": "https://census.corp.local:8443/#/ticket/4f1c2a…",
  "census": { "version": "0.65.0", "server": "CENSUS01" }
}

id is unique per event: use it to ignore a repeat. severity goes from 0 (information) to 10. data depends on the type:

Type data
asset.created, asset.changed kind (created, change, software, state, status, user, relation…), message, asset {id, name, ip, mac, type, os, site, domain}
alert rule_id, rule, subject, text (the alert as plain text), status (emailed / logged…)
audit.signin, audit.change kind (login, login_failed, logout, change), user, ip, action, target, status (HTTP status of a change)
ticket.created ticket {id, number, subject, status, priority, category, requester, requester_email, source, assignee}
ticket.updated kind (reply, internal, event), public, author, text, ticket {id, number, subject, status, priority}

Census doesn't follow redirects (enter the final address) and treats any answer other than 2xx as a failure.

Checking the signature#

With a signing secret, every request carries X-Census-Timestamp (Unix seconds) and X-Census-Signature: sha256=<hex>, the HMAC-SHA256 of timestamp + "." + body with your secret. Check it and reject old timestamps so nobody else can post to your receiver:

import hmac, hashlib, time

def from_census(secret: bytes, headers, body: bytes) -> bool:
    ts = headers["X-Census-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    want = "sha256=" + hmac.new(secret, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, headers["X-Census-Signature"])

Other headers: X-Census-Event (the type) and X-Census-Delivery (the event id).

Syslog (SIEM)#

Enter the syslog server (name or address, optionally :port; default 514, or 6514 for TLS), the protocol and the format. Messages follow RFC 5424 with facility local0, the host name of the Census server and app name census; over TCP and TLS each message is one line.

  • UDP is the simplest but can lose messages on a busy network and has no encryption. Prefer TCP, or TLS when the events cross networks you don't control.
  • TLS checks the server's certificate against the Census server's trusted roots. For a receiver with a self-signed certificate on your own network, tick Don't verify the receiver's certificate.

CEF (Common Event Format) is parsed by Microsoft Sentinel, QRadar and ArcSight without setup:

CEF:0|Steward IT|Census|0.65.0|audit.signin|bob sign-in failed|6|rt=1791643391000 cat=audit.signin externalId=… dvchost=CENSUS01 suser=bob src=10.0.0.9 act=Sign-in failed outcome=failure request=https://census.corp.local:8443/#/audit
CEF field Content
Signature ID / Name / Severity event type / title / 0–10
rt, cat, externalId, dvchost time (ms), event type, event ID, Census server
dhost, dst, dmac, cs1–cs3 assets: name, IPv4 address, MAC; type, OS, site (labels in csNLabel)
suser, src, act, outcome sign-ins and changes: login, address, action, success/failure
msg asset history text, alert text, ticket note text
request link to the record in Census

Microsoft Sentinel: install the Common Event Format (CEF) via AMA data connector on a Linux log forwarder (rsyslog), point Census at that forwarder with CEF over TCP 514, and the events appear in the CommonSecurityLog table (DeviceVendor == "Steward IT", DeviceProduct == "Census").

JSON puts the same Census JSON as the webhook into the message part, for Graylog, Elastic, Wazuh and other tools that parse JSON.

Splunk HEC#

In Splunk, turn on the HTTP Event Collector (Settings › Data inputs › HTTP Event Collector) and create a token. In Census enter the collector address, e.g. https://splunk.corp.local:8088 (Census adds /services/collector/event; enter a full path to use another endpoint), the token and optionally an index (else the token's default index). Census sends up to 100 events per request with sourcetype census:<type> (e.g. census:asset.created), source steward-it-census and the Census JSON as the event. Splunk Cloud: use the HEC address your stack shows (https://http-inputs-<stack>.splunkcloud.com).

Syncing assets to ServiceNow and Jira Assets#

Census can keep a CMDB filled from what it discovers. Under Configuration › Integrations › Sync assets to ServiceNow / Jira Assets, click Add an asset sync, pick where the assets go, enter the address and the sign-in, click Test the connection, choose which assets to send and how often, and save. The sync runs a few seconds after saving and then every hour or once a day; Sync now starts it at once.

How it works, for both:

  • One way. Census is the source of the discovered data: it creates and updates records, and never reads changes back. Fields Census has no value for are left alone, so what you keep by hand in the CMDB (support group, cost center…) stays.
  • Only what changed. Census remembers what it sent for each asset and sends an asset again only when one of its values changed. A large inventory with no changes costs a few requests per run.
  • Updated, not duplicated. Census remembers which record each asset became and updates that record from then on, also after the computer is renamed or re-imaged.
  • Which assets: all active assets, some asset types, or the members of an asset group.
  • Deleted and archived assets: deleting an asset in Census never deletes the record. For ServiceNow you can tick Mark records of archived assets as Retired: an archived asset's record gets the install status Retired (and Installed again if the asset comes back). Jira objects of archived assets stay as they are.
  • The status column shows the last run: created, updated, unchanged and failed assets, with the last errors. A run that stopped (wrong password, instance unreachable) is tried again within the hour.
  • When ServiceNow or Jira asks Census to slow down (HTTP 429), Census waits as long as it's told and continues.

ServiceNow CMDB#

On the ServiceNow side

  1. Create an integration user (User Administration › Users, tick Web service access only) with the roles itil and cmdb_inst_admin (or a custom role that may read and write the CMDB classes below, core_company, cmn_location and, for Assigned to, read sys_user). Census signs in with that user name and password. Instead you can use OAuth client credentials: create an OAuth API endpoint for external clients (System OAuth › Application Registry), enable the client credentials grant for it, and give it that user.
  2. Add Steward IT Census as a choice of the Discovery source field (Configuration › CI Class Manager, or the choice list of cmdb_ci.discovery_source), or enter an existing source in Census. The Identification and Reconciliation API refuses unknown sources.

Write method. By default Census writes through ServiceNow's Identification and Reconciliation API (IRE): ServiceNow's own identification rules decide whether a record already exists (by serial number, name or MAC address), and reconciliation rules decide which source may change which field. Census sends up to 100 assets per request. When the integration user may not use it, Census falls back to the Table API: it finds the record by the Census ID in Correlation ID, else by serial number, else by name, and updates it, or creates a new one. You can also fix the method to one of them.

Classes and fields

Census asset type ServiceNow class
Windows, macOS, Chrome OS cmdb_ci_computer
Windows Server cmdb_ci_win_server
Linux cmdb_ci_linux_server
Unix cmdb_ci_unix_server
Server, Hypervisor cmdb_ci_server
Virtual Machine by its operating system, as above
Network Device, Switch, Router, Firewall, Access Point cmdb_ci_netgear
Printer cmdb_ci_printer
anything else cmdb_ci_hardware

Every record gets Name, Serial number, Model number, IP address, MAC address, DNS domain, Fully qualified domain name and the Census asset ID in Correlation ID. Manufacturer and Location are set when ServiceNow has a company or location with exactly that name. Computers and servers also get Operating system, OS version, RAM (MB), CPU name, CPU core count and Disk space (GB). With Fill Assigned to ticked, Assigned to is set when ServiceNow has one user whose user name, email or name matches the asset's assigned user. With IRE, Census also sends the MAC address as a network adapter for identification.

Jira Service Management Assets#

Assets comes with Jira Service Management Premium and Enterprise (Cloud).

On the Jira side

  1. Use an Atlassian account that may create and edit objects in the object schema (an Assets schema manager or object schema user role with edit rights). Create an API token for it at id.atlassian.com › Security › API tokens. Census signs in with the account's email address and that token.
  2. In the object type the assets go into (for example Computers or Hardware), add a text attribute called Census ID. Census stores each asset's ID there, so it finds its objects again.

In Census, enter your site address (https://yourcompany.atlassian.net), the email address and the token, then click Load from Jira and pick the object schema and object type. Census maps its values to the type's attributes by name (Name, Serial Number, Manufacturer, Model, Operating System, IP Address, MAC Address, RAM, CPU, Location, Census ID…); change the mapping where your attributes are called differently, or set a value to (not sent). Only plain attributes (text, number, date…) can be mapped; reference, user and status attributes can't. Name must be mapped.

Matching. Census updates the object it made or found before. For an asset it hasn't sent yet, it looks for an object of the type whose Census ID attribute holds the asset's ID (else whose serial number attribute holds the serial number), updates it when exactly one matches, and creates an object otherwise. If several objects match, the asset is listed as failed instead of guessing.

Security#

  • Only administrators see and change integrations; each change is in the audit log. The signing secret, the Splunk token, the ServiceNow password or client secret and the Jira API token are stored encrypted like credentials and never shown again.
  • Give the ServiceNow user and the Atlassian account only the rights the sync needs.
  • Census only sends; integrations open no port on the Census server.
  • Events can contain device names, addresses, user names and ticket text. Send them only to receivers you control, and use HTTPS or TLS when they leave your network.