How to Build Custom Zabbix Webhook Alerts with JavaScript (DingTalk Example)

Background

Zabbix 4.4 introduced support for custom JavaScript in webhook media types, enabling front‑end style alert notifications that are easier to maintain, import/export, and require no backend script debugging.

Implementation Principle

The JavaScript receives parameters, builds an HTTP request, and sends it. Official documentation provides many example webhook types that can be copied and adapted.

Zabbix‑Provided JavaScript Objects

Logging Object

Log(loglevel, message) : writes a log entry to Zabbix with the specified level.

HTTP Request Object

AddHeader(name, value) : adds an HTTP header for subsequent requests.

ClearHeader() : clears previously set headers; defaults Content‑Type to

application/json

for JSON data.

GetHeaders() : returns received HTTP headers.

Get(url, data) , Put(url, data) , Post(url, data) , Delete(url, data) : send the corresponding HTTP method and return the response.

Status() : returns the status code of the last request.

SetProxy(proxy) : sets an HTTP proxy if needed.

Example: Creating a Jira Issue

<code>try{Zabbix.Log(4,'jira webhook script value='+value);var result={"tags":{"endpoint":"jira"}},params=JSON.parse(value),req=new CurlHttpRequest(),fields={},resp;req.AddHeader('Content-Type: application/json');req.AddHeader('Authorization: Basic '+params.authentication);fields.summary=params.summary;fields.description=params.description;fields.project={"key":params.project_key};fields.issuetype={"id":params.issue_id};resp=req.Post('https://tsupport.zabbix.lan/rest/api/2/issue/',JSON.stringify({"fields":fields}));if(req.Status()!=201){throw 'Response code: '+req.Status();}resp=JSON.parse(resp);result.tags.issue_id=resp.id;result.tags.issue_key=resp.key;}catch(error){Zabbix.Log(4,'jira issue creation failed json : '+JSON.stringify({"fields":fields}));Zabbix.Log(4,'jira issue creation failed : '+error);result={};}return JSON.stringify(result);</code>

Configuring a Webhook Media Type

You can import an existing XML definition from the Zabbix source or create a custom one. Required variables include

URL

,

HTTPProxy

,

To:{ALERT.SENDTO}

,

Subject:{ALERT.SUBJECT}

, and

Message:{ALERT.MESSAGE}

. The media type can also process tags returned in JSON.

Data Validation

Validate both input parameters (e.g., missing values, macro resolution) and the external system's response (presence, HTTP status, expected format, required fields, and error codes).

Logging Requirements

Provide debug‑level logs for troubleshooting.

Do not create higher‑level logs; Zabbix records failed webhooks at warning level automatically.

Prefix log entries with the webhook name.

Avoid logging every step.

Custom DingTalk Webhook Example

First, create a DingTalk robot with a custom keyword and obtain its webhook URL, e.g.,

https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN

.

Then add a new webhook media type in Zabbix, fill in the alert message, recipient, and webhook URL, and use the following script:

<code>var Dingding = {params:{},proxy:null,setParams:function(params){if(typeof params!=='object'){return;}Dingding.params=params;},request:function(){var data={msgtype:"markdown",markdown:{title:"报警",text:"## 通知:\n "+Dingding.params.Message},at:{atUserIds:[Dingding.params.To],isAtAll:false}},response,url=Dingding.params.URL,request=new HttpRequest();request.addHeader('Content-Type: application/json');if(typeof Dingding.HTTPProxy!=='undefined' && Dingding.HTTPProxy!==''){request.setProxy(Dingding.HTTPProxy);}if(typeof data!=='undefined'){data=JSON.stringify(data);}Zabbix.Log(4,"[Dingding Webhook] message is: "+data);response=request.post(url,data);Zabbix.log(4,'[ Dingding Webhook ] Received response with status code '+request.getStatus()+'\n'+response);if(response!==null){try{response=JSON.parse(response);}catch(error){Zabbix.log(4,'[ Dingding Webhook ] Failed to parse response');response=null;}}if(request.getStatus()!=200 || response.errcode!=0){var message='Request failed with status code '+request.getStatus();if(response!==null && typeof response.errmsg!=='undefined'){message+=': '+JSON.stringify(response.errmsg);}throw message+'. Check debug log for more information.';}return response;}};try{var params=JSON.parse(value);if(typeof params.URL!=='undefined' && typeof params.To!=='undefined' && typeof params.Message!=='undefined'){Zabbix.log(4,'[ Dingding Webhook ] webhookURL "'+params.URL+'" sendto "'+params.To+'"');}else{throw 'Missing parameter. URL, message, to parameter is required';}if(params.HTTPProxy){Dingding.proxy=params.HTTPProxy;}Dingding.setParams(params);Dingding.request();return 'OK';}catch(error){Zabbix.log(3,'[ Dingding Webhook ] ERROR: '+error);throw 'Sending failed: '+error;}</code>

After saving, test the media type by providing the required parameters; the script will send a markdown‑formatted alert to DingTalk.

The alert message supports markdown, allowing richer formatting.