Zabbix Integration Developer Guide

Zabbix — Developer Guide

How the Zabbix integration works, where it lives, and the traps. The user page is Zabbix.

Contributed by Carl Steynvaard (Open Resilience), October 2026, as part of a package of integrations and modules he built and ran in production on FreeITSM 3.8.1. The design — what happens on a problem, a repeat and a recovery, and the event log — is his. The code was rebuilt to FreeITSM's conventions; what changed and why is worth reading before contributing an integration of your own.

---

The shape

Zabbix ──webhook media type──▶ api/external/zabbix/alert.php ──▶ zabbixHandleEvent()   includes/integrations/zabbix.php
                                (POST JSON, token)                    │
                                                                      ├─ problem   → TicketsService::createTicket + ticket_cmdb_objects
                                                                      ├─ repeat    → a message on the ticket's thread
                                                                      ├─ recovery  → a message + TicketsService::updateTicket(status)
                                                                      └─ always    → a row in zabbix_events

System → Integrations → Zabbix (system/integrations/zabbix.php) ──▶ api/system/zabbix_settings.php   (administrators)

Nothing calls Zabbix. It is a monitoring-kind provider in the registry (includes/integrations/integrations.php): one endpoint and one token, so the Integrations index shows it as Configured / Not set up, like Tika, rather than counting connections.

📁 Files

File	What it is
includes/integrations/zabbix.php	Everything: settings and defaults, the token, CMDB matching, zabbixHandleEvent()
api/external/zabbix/alert.php	The endpoint Zabbix calls. POST JSON only; checks the token; 64 KB limit
api/system/zabbix_settings.php	The settings page's API: get, save, rotate, test, export (the import file). Administrators only
system/integrations/zabbix.php	The settings page
system/integrations/help_zabbix.php	The in-app setup guide, included by help.php
zabbix_events (table)	Every event received: problem_id, event_value, host, trigger, severity, the ticket, the action taken, a detail
tests/zabbix-integration.php	34 checks through the real endpoint and the settings API with events shaped as the media type sends them
tests/zabbix/run.php + docker-compose.yml	12 checks against a real Zabbix 7.0 in Docker, through the imported media type

Settings are system_settings rows: zabbix_token (encrypted — it is in ENCRYPTED_SETTING_KEYS), zabbix_requester_email, zabbix_requester_name, zabbix_tenant_id, zabbix_priority_map (JSON, severity → priority id), zabbix_resolve_status_id (0 = leave the status alone), zabbix_team_id, zabbix_origin_id, zabbix_link_cmdb.

What each event does

The media type's parameters are endpoint and token (this install's), then Zabbix macros: event_id = {EVENT.ID}, event_value = {EVENT.VALUE} (1 problem, 0 recovery), severity = {EVENT.NSEVERITY}, host = {HOST.NAME}, trigger = {EVENT.NAME}, message = {ALERT.MESSAGE} and url = {$ZABBIX.URL}/tr_events.php?… — the link back, which is empty (and dropped) unless the {$ZABBIX.URL} macro is set in Zabbix. The last, http_proxy, is empty unless Zabbix must reach FreeITSM through a proxy; the script calls req.setProxy() only when it is filled in. The script posts the event to endpoint as JSON, renaming event_id to problem_id, and throws on any answer but 200, so a failure shows in Zabbix's action log with FreeITSM's own words.

1. zabbixOpenTicketFor($problemId) — the latest logged event for this problem that has a ticket, if that ticket still exists, is not merged and is not closed.
2. Recovery — a message on the thread, then TicketsService::updateTicket(['status_id' => …]). A closure rule may refuse; the ticket stays open and the refusal goes in the log's detail.
3. Repeat or update (value 1, open ticket) — a message on the thread.
4. New problem — CMDB match, company, then TicketsService::createTicket() with the mapped priority, the configured team and origin, then the CMDB link.

Every outcome is logged. A GET_LOCK on the problem id serialises a problem and its first repeat arriving together, which would otherwise open two tickets.

🔑 Why recovery pairing works

Zabbix sends a recovery with the problem's {EVENT.ID}, not a new one — that is the only reason a recovery can find its ticket. It is documented, but it is exactly the kind of thing worth proving rather than trusting, so tests/zabbix/run.php asserts it against a real Zabbix: the recovery's problem_id equals the problem's, and it resolves the ticket the problem opened.

The media type: one definition, three uses

zabbixMediaTypeScript(), zabbixMediaTypeParameters() and zabbixMediaTypeTemplates() in includes/integrations/zabbix.php are the only copy. The settings page shows them for setting up by hand, zabbixMediaTypeYaml() turns them into the import file (export action, Download for Zabbix import), and tests/zabbix/run.php downloads that file from the real API and imports it into a real Zabbix — so what is tested is exactly what an administrator imports.

The file's shape is Zabbix 7.0's own configuration.export output, taken from a real server rather than the documentation: type: WEBHOOK; a parameter with an empty value is written with no value: line; timeout (30s) and status (enabled) are omitted because they are the defaults; message templates are event_source: TRIGGERS with operation_mode PROBLEM / RECOVERY / UPDATE. Values are single-quoted with '' for a quote; the script and messages are literal blocks.

⚠️ The file carries the token. The export action is administrators-only and sends Cache-Control: no-store.

"Try it"

Send a test alert and Send the recovery on the settings page: action: 'test' sends a problem (step: 'problem', a fresh id freeitsm-test-<8 hex>, host freeitsm-test) and then its recovery (step: 'recovery') through zabbixHandleEvent() itself — the same path a real alert takes, so it proves the settings and the incident they produce rather than a pretend route. The recovery step accepts only an id of that shape, so the button can never recover a real problem. It deliberately does not go through the HTTP endpoint: a server often cannot reach its own public address (hairpin NAT), and a failure there would say nothing about Zabbix. The network half belongs to Zabbix's own Test button, and the page says so.

The traps

• TRAP: never guess between companies when matching a host. Two companies may each have a web01. Several matches → the one in the configured company if exactly one is, otherwise none. Linking either would put one company's alert on the other's server.
• The company comes from the server, not a setting. An alert about a client's server belongs in that client's queue. The setting is only the fallback for a host the CMDB does not know.
• No priority names. The default map reads this install's priorities by display_order (higher = more urgent, as Watchtower reads it): Disaster → the most urgent, High → the next, Average → the default, the rest → the least. The contributed version looked for P1 - Critical, which no stock install has.
• Repeats and recoveries are thread messages, not notes. ticket_notes.analyst_id is NOT NULL, and there is no analyst — the actor is ActorContext::system('Zabbix'). A message from the monitoring requester is also simply what a monitoring system that emails the desk looks like, which is where an analyst reads. The text is stored escaped (nl2br(htmlspecialchars())) — it came from outside.
• The default requester cannot receive mail (zabbix@monitoring.invalid — .invalid is reserved and never routes), so an auto-acknowledge workflow on ticket.created emails nobody.
• A link that is not http(s) is dropped, not shown — the URL parameter is Zabbix-supplied text.
• The endpoint is on CSRF_EXEMPT_PATHS (api/external/): Zabbix is cross-origin by design and never carries a login cookie. The token is the credential, compared with hash_equals, and an install with no token yet refuses everything rather than comparing against an empty string.

What changed from the contribution, and why

The contributed code worked in the production it was written for. It could not work in FreeITSM as shipped, and the reasons are the ones any integration has to get right:

The contribution	Here	Why
Settings and the event log in a separate SQLite file at /var/www/data	system_settings and a zabbix_events table	A Linux-only path, outside backups and Database Verification; the token stored readable
Tickets in "the first company" (ORDER BY id LIMIT 1)	The server's company, else the configured one	On a multi-company install every alert landed in one company
Priorities by name (P1 - Critical)	By display_order, chosen on the page	Stock installs have Low…Urgent
Acted as the lowest-numbered analyst	ActorContext::system('Zabbix')	That is usually the administrator — every note looked as if the admin wrote it
Requester monitoring@example.com	A configurable address, defaulting to .invalid	example.com is somebody's real domain to a mail server
Repeats as internal notes	Thread messages	No analyst to own a note (see above)
Its own admin check and CSRF token; hard-coded English	admin_api_guard.php, the app's CSRF, t()	One implementation of each
Installed by patching core files (register-patch.php)	A registry entry	A patch that edits upstream files breaks on every upgrade

Testing

Without Zabbix: php tests/zabbix-integration.php — token required (and a GET refused), problem → incident with the mapped priority and the CMDB link, repeat → same ticket, recovery → resolved, unknown host, severity by name, markup stored as text, a bad link dropped, the log. Pauses ticket.created workflows so nobody is emailed, and removes everything it makes.

Against a real Zabbix:

docker compose -f tests/zabbix/docker-compose.yml up -d     # Zabbix 7.0 LTS: server, web (http://localhost:8086, Admin / zabbix), MySQL
php tests/zabbix/run.php
docker compose -f tests/zabbix/docker-compose.yml down -v   # when finished

run.php downloads the import file from the real settings API and imports it into Zabbix (renamed for the run, so it never touches a media type somebody made), then builds a host, a trapper item, a Disaster trigger, an alert user and an action — then pushes 97 into the item (problem), acknowledges it (update), pushes 40 (recovery), and checks FreeITSM at each step. When nothing arrives it prints Zabbix's own view — the item, the problem and the alert's error — which is how both setup traps below were found:

• A media type created through the API starts disabled in Zabbix 7 (Media type disabled in the action log). An imported one is enabled - the import file leaves status at its default.
• Zabbix never notifies the user who made an update. Acknowledging as the same user the alerts go to produces no update at all, so the run sends alerts to a user of its own. The help page tells administrators the same.

Zabbix reaches FreeITSM on the host through host.docker.internal, so the web server must listen beyond 127.0.0.1. Override with ZABBIX_TO_FREEITSM, ZABBIX_API and ZABBIX_SERVER_CONTAINER.

---

Related: Zabbix · External issue trackers — Developer Guide · CSRF protection — Developer Guide · Developer Tests