Nagios event handlers are scripts that run when a host or service changes state. By pointing an event handler at the Alert24 incidents API, every Nagios alert automatically becomes a tracked incident in Alert24 — with deduplication so repeated check failures don't create duplicate incidents.

Before you start

You'll need:

An Alert24 API key with write or incidents scope (Settings → API Keys)
Nagios Core or Nagios XI with event handlers enabled (enable_event_handlers=1 in nagios.cfg)

Create the event handler script

Save this to /usr/local/nagios/libexec/alert24_incident.sh and make it executable (chmod +x):

#!/bin/bash
# Alert24 incident event handler
# Args: $1=state $2=statetype $3=service_desc $4=host_name $5=output

STATE="$1"
STATE_TYPE="$2"
SERVICE_DESC="$3"
HOST="$4"
OUTPUT="$5"
API_KEY="ak_live_YOUR_KEY"

# Only fire on HARD state changes to avoid noise from soft states
if [ "$STATE_TYPE" != "HARD" ]; then
  exit 0
fi

if [ "$STATE" = "OK" ] || [ "$STATE" = "UP" ]; then
  # Service recovered — Alert24 auto-resolves via alias dedup, nothing to do
  exit 0
fi

# Map Nagios state to Alert24 severity
case "$STATE" in
  CRITICAL|DOWN) SEVERITY="critical" ;;
  WARNING)       SEVERITY="high" ;;
  UNKNOWN)       SEVERITY="medium" ;;
  *)             SEVERITY="medium" ;;
esac

TITLE="$HOST${SERVICE_DESC:+: $SERVICE_DESC} is $STATE"
ALIAS="nagios-${HOST}-${SERVICE_DESC// /_}"

curl -s -X POST https://app.alert24.net/api/v1/incidents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"$TITLE\",
    \"description\": \"$OUTPUT\",
    \"severity\": \"$SEVERITY\",
    \"alias\": \"$ALIAS\",
    \"source\": \"nagios\",
    \"tags\": [\"nagios\", \"$HOST\"]
  }"

Wire it up in Nagios

Define an event handler command in commands.cfg:

define command {
  command_name  alert24_incident
  command_line  /usr/local/nagios/libexec/alert24_incident.sh \
                  "$SERVICESTATE$" "$SERVICESTATETYPE$" \
                  "$SERVICEDESC$" "$HOSTNAME$" "$SERVICEOUTPUT$"
}

Add the handler to any service or host definition:

define service {
  use                   generic-service
  host_name             web-prod-01
  service_description   HTTP Check
  check_command         check_http
  event_handler         alert24_incident
  event_handler_enabled 1
}

For host-level handlers, use $HOSTSTATE$ and $HOSTSTATETYPE$ instead.

Deduplication

The alias field acts as a dedup key. If Nagios re-fires the same check failure, Alert24 increments the occurrence count on the existing incident rather than opening a new one. Use a stable alias like nagios-hostname-servicename.

Tips

HARD vs SOFT states: The STATE_TYPE check in the script skips SOFT states (in-progress retries). This prevents a flood of incidents during the retry period.
Auto-resolution: To auto-resolve Alert24 incidents on recovery, call PUT /api/v1/incidents/{id} with {"status":"resolved"} in the OK/UP branch. You'll need to store/look up the incident ID — using the alias with the GET /api/v1/incidents?alias=... endpoint is the cleanest approach.
Nagios XI: In Nagios XI, you can also use the built-in Outbound Check Results REST API or configure this handler the same way via the config editor.