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.

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.

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.

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.

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.

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.

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.

• 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 ([email protected] — .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.

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:

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