Integrations

An integration is where another system meets the desk. It gives that system an endpoint to call, such as a monitoring tool sending its alerts, and turns each call into a record: an event, an incident, a problem or a case. It can also hold a connection, which is how the desk calls the other system, and the webhooks that send it the desk's events. Every call in and out is kept in the integration's log for 30 days.

Integrations are set up under Platform → Integrations by people with the integration.settings permission (admins). Auditors, with integration.read, can open them and their logs but change nothing. Each integration belongs to one organization.

Creating an integration

1. Under Platform → Integrations, choose New integration.
2. Under Start from, pick a connector:
   • Generic JSON works for any system that can send JSON over HTTPS.
   • SigNoz comes with SigNoz's alerts already mapped to events. Firing alerts open or update an event, and resolved alerts close it. It needs the Events plugin.
3. Give the integration a name, and a description if you like, then choose Create integration.
4. Copy the endpoint's address and secret to the other system, following the steps in the dialog.

[!IMPORTANT] The secret is shown once. Afterwards the desk shows only its first and last characters. If it is lost, give the endpoint a new one.

Endpoints

Each endpoint has its own address, https://<your desk>/api/v1/in/ie_…, and its own secret. Add one for each kind of call the other system makes. Edit opens an endpoint:

Field	What it does
How the caller signs in	Bearer token: the secret in Authorization: Bearer …. Basic: the secret as the password, for tools that only offer a user name and password (like SigNoz). Signed body (HMAC): the body signed with the secret, the same way the desk signs its webhooks.
Each call becomes	What the desk makes from each call: a case, or a record of a plugin that is on (an event, an incident, a problem). An endpoint stays off until this is picked.
Unit	Where new records are placed. When it's empty, they go in the organization.
Sample call	A body as the other system sends it. The placeholders are picked from it, and Test runs it.
List of items	When a call carries several things, like SigNoz's alerts, give the path to the list. Each item is then handled on its own.
Duplicate key	A path whose value is the same when the other system retries, like item.fingerprint. A repeat within 24 hours is answered without being handled again. An Idempotency-Key header does the same.
Fields	What each field of the record is filled with: fixed text, placeholders like {{item.labels.severity}}, or both. The { } button lists every placeholder the sample offers, with its value from the sample.
IP allowlist	Accept calls only from the addresses on one of the organization's IP allowlists.
Calls a minute	Calls beyond this are refused with 429 (120 by default).
On	When it's off, calls are refused.
Capture the next call	The next call is saved as the sample and not handled. This is the easiest way to get a real sample: turn it on, make the other system send something, then pick the fields.

The placeholders are {{body.…}} for the whole body, {{item.…}} for the item being handled, {{headers.…}} (in lower case) and {{query.…}}.

Test with the sample saves the endpoint and shows what the sample would do, item by item, without creating anything. For example, "Would create an incident: High CPU on db-prod-01", or "Title came out empty" when a field is missing.

A new secret

From an endpoint's ⋯ menu:

• New secret (old one works 24 hours) gives the endpoint a new secret. The current one keeps working for a day, while the other system is updated.
• Rotate immediately stops the current secret right away. Use it when the secret may have leaked.

Connection

The Connection tab holds how the desk calls the other system, for automations and plugins that look things up or send updates there.

• Base address: in production it must be https:// and resolve to a public address.
• Authentication: a bearer token, an API key in a header, a user name and password, or OAuth client credentials. The desk fetches and renews OAuth tokens itself.
• Extra headers and a timeout.

Credentials are kept encrypted and never shown again. Leave a credential field empty to keep the one that is stored. Call sends a GET to the path you give, to check the connection. That call is logged like any other.

Webhooks

The Webhooks tab lists the webhooks that send events to this system. Link a webhook adds one of the organization's webhooks here. Webhooks are still created and changed under Webhooks.

Log

The Log tab shows every call of the last 30 days, newest first. Filter it by direction, outcome or endpoint, and open a call to see its body, where it came from and what it did.

Outcome	Meaning
Queued	Accepted, about to be handled.
Done	It created or updated something. Open the call for links to the records.
Ignored	There was nothing to do, such as a resolved alert for an event that is already closed.
Failed	It couldn't be handled. The reason says why, such as a required field that came out empty.
Refused	Turned away before being handled: wrong secret, an address that isn't allowed, too many calls, or not JSON. The body isn't kept.
Duplicate	A repeat of an earlier call (the same duplicate key within 24 hours).
Captured	Saved as the sample (Capture the next call).

Run again handles a call once more as a new call in the log, linked to the first one. Use it after fixing a mapping, or after turning on the plugin a call needed.

Export saves the log of a period as Excel, CSV or PDF for auditors. Exports are recorded in the export log with a checksum.

For auditors

• Creating, changing and deleting integrations and endpoints, new secrets, connection changes and calls run again are all in the audit log.
• Secrets and credentials are never shown again after they are set, and are kept encrypted.
• Records made from a call are made by System and name the integration they came from.

SigNoz

1. Make sure the Events plugin is on (Platform → Plugins).
2. Create an integration from the SigNoz connector.
3. In SigNoz, open Settings → Alert Channels → New Alert Channel and choose the type Webhook.
4. Set Webhook URL to the endpoint's address. Set the user name to anything (for example itsm-engine) and the password to the secret.
5. Turn on Send resolved alerts, save, and pick the channel on the alert rules that should reach the desk.

The connector maps the alert's summary, description, severity, fingerprint (to keep one event per alert), host (host_name, matched to a configuration item), service (service_name) and its link back to SigNoz.

See also: the integrations API.