[comment]: # ({56bf7160-56bf7160}) # 4 Webhook [comment]: # ({/56bf7160-56bf7160}) [comment]: # ({6584b266-6584b266}) #### Overview The webhook media type is useful for making HTTP calls using custom JavaScript code for straightforward integration with external software such as helpdesk systems, chats, or messengers. You may choose to import an integration provided by Zabbix or create a custom integration from scratch. [comment]: # ({/6584b266-6584b266}) [comment]: # ({b3b80c04-27a06b1f}) #### Integrations The following integrations are available, allowing predefined webhook media types to be used for pushing Zabbix notifications to: - [brevis.one](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/brevis.one/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Discord](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/discord/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Event-Driven Ansible](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/event_driven_ansible/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Express.ms messenger](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/express.ms/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Github issues](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/github/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [GLPi](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/glpi/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [iLert](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/ilert/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [iTop](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/itop/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Jira](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/jira/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Jira Service Desk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/jira_servicedesk/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [ManageEngine ServiceDesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/manageengine_servicedesk/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Mantis Bug Tracker](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/mantisbt/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Mattermost](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/mattermost/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Microsoft Teams](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/msteams/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [LINE](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/line/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Opsgenie](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/opsgenie/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [OTRS](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/otrs_ce/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Pagerduty](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/pagerduty/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Pushover](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/pushover/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Redmine](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/redmine/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Rocket.Chat](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/rocketchat/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [ServiceNow](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/servicenow/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [SIGNL4](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/signl4/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Slack](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/slack/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [SolarWinds](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/solarwinds/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [SysAid](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/sysaid/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Telegram](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/telegram/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [TOPdesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/topdesk/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [VictorOps](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/victorops/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Zammad](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/zammad/README.md?at=refs%2Fheads%2Frelease%2F6.4) - [Zendesk](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/media/zendesk/README.md?at=refs%2Fheads%2Frelease%2F6.4) ::: notetip In addition to the services listed here, Zabbix can be integrated with **Spiceworks** (no webhook is required). To convert Zabbix notifications into Spiceworks tickets, create an [email media type](/manual/config/notifications/media/email) and enter Spiceworks helpdesk email address (e.g. help\@zabbix.on.spiceworks.com) in the profile settings of a designated Zabbix user. ::: [comment]: # ({/b3b80c04-27a06b1f}) [comment]: # ({c3940a4c-d84f1038}) #### Configuration To start using a webhook integration: 1. Locate required .xml file in the `templates/media` directory of the downloaded Zabbix version or download it from Zabbix [git repository](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse) 2. [Import](/manual/xml_export_import/media#importing) the file into your Zabbix installation. The webhook will appear in the list of media types. 3. Configure the webhook according to instructions in the *Readme.md* file (you may click on a webhook's name above to quickly access *Readme.md*). To create a custom webhook from scratch: - Go to *Alerts → Media types* - Click on *Create media type* The **Media type** tab contains various attributes specific for this media type: ![](../../../../../assets/en/manual/config/notifications/media/media_webhook_express.png) All mandatory input fields are marked with a red asterisk. The following parameters are specific for the webhook media type: |Parameter|Description| |--|--------| |*Parameters*|Specify the webhook variables as the attribute and value pairs.
For preconfigured webhooks, a list of parameters varies, depending on the service. Check the webhook's *Readme.md* file for parameter description.
For new webhooks, several common variables are included by default (URL:, HTTPProxy:, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}), feel free to keep or remove them.

Webhook parameters support [user macros](/manual/appendix/macros/supported_by_location_user), all [macros](/manual/appendix/macros/supported_by_location) that are supported in problem notifications and, additionally, {ALERT.SENDTO}, {ALERT.SUBJECT}, and {ALERT.MESSAGE} macros.

If you specify an HTTP proxy, the field supports the same functionality as in the item configuration [HTTP proxy](/manual/config/items/itemtypes/http#configuration) field. The proxy string may be prefixed with `[scheme]://` to specify which kind of proxy is used (e.g. https, socks4, socks5; see [documentation](https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html)).| |*Script*|Enter JavaScript code in the block that appears when clicking in the parameter field (or on the view/edit button next to it). This code will perform the webhook operation.
The script is a function code that accepts parameter - value pairs. The values should be converted into JSON objects using JSON.parse() method, for example: `var params = JSON.parse(value);`.

The code has access to all parameters, it may perform HTTP GET, POST, PUT and DELETE requests and has control over HTTP headers and request body.
The script must contain a return operator, otherwise it will not be valid. It may return OK status along with an optional list of tags and tag values (see *Process tags* option) or an error string.

Note that the script is executed only after an alert is created. If the script is configured to return and process tags, these tags will not get resolved in {EVENT.TAGS} and {EVENT.RECOVERY.TAGS} macros in the initial problem message and recovery messages because the script has not had the time to run yet.
*Note*: Using local variables instead of global ones is recommended to make sure that each script operates on its own data and that there are no collisions between simultaneous calls (see [known issues](/manual/installation/known_issues#use-case-with-global-variables-shared-across-webhook-calls)).

See also: [Webhook development guidelines](https://www.zabbix.com/documentation/guidelines/en/webhooks), [Webhook script examples](/manual/config/notifications/media/webhook/webhook_examples), [Additional JavaScript objects](/manual/config/items/preprocessing/javascript/javascript_objects).
| |*Timeout*|JavaScript execution timeout (1-60s, default 30s).
Time suffixes are supported, e.g. 30s, 1m.| |*Process tags*|Mark the checkbox to process returned JSON property values as tags. These tags are added to any existing problem tags.
Note that when using [webhook tags](https://www.zabbix.com/documentation/guidelines/en/webhooks#webhook-tags), the webhook must return a JSON object containing at least an empty tags object: `var result = {tags: {}};`
Examples of tags that can be returned: *Jira ID: PROD-1234*, *Responsible: John Smith*, *Processed:*| |*Include event menu entry*|Mark the checkbox to include an entry in the [event menu](/manual/web_interface/menu/event_menu) linking to a created external ticket.
An entry will be included for each webhook that is enabled and has this checkbox marked. Note that if the *Menu entry name* and *Menu entry URL* parameters contain any [{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) macros, an entry will be included only if these macros can be resolved (that is, the event has these tags defined).
If marked, the webhook should not be used for sending notifications to different users (consider creating a [dedicated user](/manual/config/notifications/media/webhook#user_media) instead) and should not be used in multiple alert actions [for a single problem event](/manual/config/notifications/media/webhook#configuring-alert-actions).| |*Menu entry name*|Specify the menu entry name.
[{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) macro is supported.
This field is only mandatory if *Include event menu entry* is marked.| |*Menu entry URL*|Specify the underlying URL of the menu entry.
[{EVENT.TAGS.}](/manual/appendix/macros/supported_by_location#events) macro is supported.
This field is only mandatory if *Include event menu entry* is marked.| See [common media type parameters](/manual/config/notifications/media#common_parameters) for details on how to configure default messages and alert processing options. ::: notewarning Even if a webhook doesn't use default messages, message templates for operation types used by this webhook must still be defined. ::: [comment]: # ({/c3940a4c-d84f1038}) [comment]: # ({d9bb0703-e5e73ea8}) #### Media type testing To test a configured webhook media type: - Locate the relevant webhook in the [list](/manual/config/notifications/media#overview) of media types. - Click on *Test* in the last column of the list (a testing window will open). - Edit the webhook parameter values, if needed. - Click on *Test*. By default, webhook tests are performed with parameters entered during configuration. However, it is possible to change attribute values for testing. Replacing or deleting values in the testing window affects the test procedure only, the actual webhook attribute values will remain unchanged. ![](../../../../../assets/en/manual/config/webhook_test1.png){width="600"} To view media type test log entries without leaving the test window, click on *Open log* (a new popup window will open). ![](../../../../../assets/en/manual/config/mediatype_test2.png){width="600"} [comment]: # ({/d9bb0703-e5e73ea8}) [comment]: # ({307f8831-b2974109}) **If the webhook test is successful:** - *"Media type test successful."* message is displayed - Server response appears in the gray *Response* field - Response type (JSON or String) is specified below the *Response* field [comment]: # ({/307f8831-b2974109}) [comment]: # ({fc3db87a-abfbc807}) **If the webhook test fails:** - *"Media type test failed."* message is displayed, followed by additional failure details. [comment]: # ({/fc3db87a-abfbc807}) [comment]: # ({1bd8ec9a-6eeec89a}) #### User media Once the media type is configured, go to the *Users → Users* section and assign the webhook media to an existing user or create a new user to represent the webhook. Steps for setting up user media for an existing user, being common for all media types, are described on the [Media types](/manual/config/notifications/media#user_media) page. If a webhook uses tags to store ticket\\message ID, avoid assigning the same webhook as a media to different users as doing so may cause webhook errors (applies to the majority of webhooks that utilize *Include event menu entry* option). In this case, the best practice is to create a dedicated user to represent the webhook: 1. After configuring the webhook media type, go to the *Users → Users* section and create a dedicated Zabbix user to represent the webhook - for example, with a username *Slack* for the Slack webhook. All settings, except media, can be left at their defaults as this user will not be logging into Zabbix. 2. In the user profile, go to a tab *Media* and [add a webhook](/manual/config/notifications/media#user_media) with the required contact information. If the webhook does not use a *Send to* field, enter any combination of supported characters to bypass validation requirements. 3. Grant this user at least read [permissions](/manual/config/users_and_usergroups/permissions#permissions_to_host_groups) to all hosts for which it should send the alerts. When configuring alert action, add this user in the *Send to users* field in Operation details - this will tell Zabbix to use the webhook for notifications from this action. [comment]: # ({/1bd8ec9a-6eeec89a}) [comment]: # ({5f524760-ac89791d}) #### Configuring alert actions Actions determine which notifications should be sent via the webhook. Steps for [configuring actions](/manual/config/notifications/action) involving webhooks are the same as for all other media types with these exceptions: - If a webhook uses [webhook tags](https://www.zabbix.com/documentation/guidelines/en/webhooks#webhook-tags) to store ticket\\message ID and handle update\\resolve operations, avoid using the same webhook in multiple alert actions for a single problem event. If {EVENT.TAGS.} exists and gets updated in the webhook, its resulting value will be undefined. To avoid this, use a new tag name in the webhook for storing updated values. This applies to Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad, and Zendesk webhooks provided by Zabbix and to most webhooks utilizing the *Include event menu entry* option. Note, however, that a single webhook can be used in multiple operations or escalation steps of the same action, as well as in different actions that will not be triggered by the same problem event due to different [conditions](/manual/config/notifications/action/conditions). - When using a webhook in actions for [internal events](/manual/config/events/sources#internal-events), ensure to mark the *Custom message* checkbox and define a custom message in the action operation configuration. Otherwise, a notification will not be sent. [comment]: # ({/5f524760-ac89791d})