OfficeCom Sentinel n8n Contract

Request

method: POST
content type: application/json
example webhook: https://n8n.example.com/webhook/ocsentinel-ingest

Required Payload Intent

The endpoint should send one signed JSON document per scan run containing:

device identity
client version
scan metadata
attack findings
CVE correlation summary
raw status fields needed for downstream NinjaOne updates

Expected Downstream Work

n8n is responsible for:

ingest validation
storage in the central backend
organization-wide aggregation
NinjaOne organization API updates

Required n8n Workflow

The webhook itself may be reachable only on the internal network. It does not require public access to the n8n editor or API. Every managed device must be able to reach the webhook URL over HTTPS.

For the isolated development environment only, HTTP is permitted at http://172.16.41.197:5678/webhook/ocsentinel-ingest. Do not reuse this URL, the development shared secret, or a disabled-TLS configuration in production.

Webhook: accept POST on the configured private URL and enable Raw Body.
Code: reject a request if X-ATN-Device, X-ATN-Timestamp, X-ATN-Nonce, X-ATN-Version, X-ATN-Payload-SHA256, or X-ATN-Signature is missing; reject timestamps outside five minutes.
Code: calculate SHA-256 over the raw request body and compare it with X-ATN-Payload-SHA256. Calculate HMAC-SHA256 over the following exact newline-separated string and compare it in constant time with X-ATN-Signature:

<device>\n<timestamp>\n<nonce>\n<version>\n<payload-sha256>

In the current n8n Webhook node, the raw bytes are exposed as Base64 at $binary.data.data. Decode this value before calculating the payload hash. Do not hash JSON.stringify($json.body): parsing and reserializing JSON changes whitespace and can change the signed byte sequence.

Postgres: insert the nonce into ocsentinel.ingest_nonce with a short expiry. If it already exists, return 409 and do not process the report.
Postgres: upsert the device, insert a row in ocsentinel.scan_report, then return 202.
A separate scheduled n8n workflow reads ocsentinel.organization_summary and ocsentinel.current_device_status to update the NinjaOne organization fields through the API.

Use an n8n credential for the shared HMAC secret and a separate n8n credential for PostgreSQL. Do not store either value in workflow JSON or this repository. For the current Docker deployment, use the private hostname ocsentinel-postgres and the restricted database role ocsentinel_n8n; see infra/dockge/README.md for the remaining credential fields.

PostgreSQL Scope

The client only knows its outward upload destination.
PostgreSQL connection details belong to the internal ingest or n8n side.
If the PostgreSQL IP changes, update the internal server-side configuration and review it during the next release.

2.9 KiB Raw Blame History