How to Modify Decimal Fields via Trigger

We are constantly on the lookout for how webhooks can be used to fill in gaps in Zendesk functionality.  Just recently, we came across a new use case that fits perfectly into our growing series of webhook workflow tutorials: Modify Decimal custom fields via ticket trigger action.  As in the other articles in this series, this workflow requirement can be accomplished by leveraging Zendesk webhooks to fire an API request after a ticket is updated.  In past articles, we have explored how to add or remove the organization on a ticket and how to set a due date X number of days from now, both in calendar days and in business days.

Setting up this workflow will be broken up into three steps:

1. Determining workflow requirements
2. Finding ticket field ID
3. Creating the webhook
4. Creating the trigger(s)

Part 1: Determining workflow requirements

The first step is of course to determine the specific business requirements. We have seen a variety of different use cases, with the common denominator being that a custom ticket field should be updated.

As an example, we will work with the case that a business is setting a specific decimal value based on the value selected in a separate drop-down field.

Part 2: Find the Ticket Field ID

Now that we have clarified our use case, the next step is to find the identifiers needed to make an update to a ticket field in the workflow.  To find the ticket field ID, go to the admin settings page, and then in the left-side panel under Objects and rules > Tickets > Fields. The URL will look like https:/{subdomain}.zendesk.com/admin/objects-rules/tickets/ticket-fields, with the {subdomain} variable being replaced by your own account subdomain.  From the ticket fields page, you can easily search for the field that you'd like to update and copy the ID from this page.  In our case, the ticket field ID is 416784304431616.

Please see the screenshot below for reference:

Part 3: Create the webhook

The next step will be to create the webhook. For inexperienced system admins, this can be one of the more difficult parts of the set up, but just follow the steps carefully and it should be possible to create it without much trouble.

First, go to to the admin panel of Zendesk, and then either search for Webhook in the top left search bar, or expand the Apps and integrations section at the bottom, and choose Webhooks under the Actions and webhooks heading.

The webhooks page will be located at a URL https://{subdomain}.zendesk.com/admin/apps-integrations/actions-webhooks/webhooks, so you can also change the {subdomain} part of this URL and navigate directly to the page.

Next, click on the Create webhook button in the upper right corner of the webhook page.

Then choose 'Trigger or automation' as the way to connect for Step 1 and then click the Next button in the lower right corner.

In Step 2, you'll need to add the details specific to your own account. First, give a name to the webhook, such as Update Ticket as the webhook will be updating the field value on a ticket.

Optionally, fill in a description to help provide context about how you are using the webhook.

For the Endpoint URL, you'll need to use the following https://{subdomain}.zendesk.com/api/v2/tickets/{{ticket.id}}.json, with the {subdomain} portion filled in with your own subdomain.  The {{ticket.id}} portion is a Zendesk placeholder which will automatically substitute the placeholder with ID of the ticket that is being updated.

Under Request method use PUT.

Request Format should be JSON which is the default value.

For Authentication, you should use the Basic authentication option. You'll need to provide a username and password. For the username, we strongly recommend using a system account profile rather than your own profile username. We have seen many times where a user account is removed after leaving the organization, and then all of the integrations set up with that user account break, and the incoming admin has no idea what broke or how to fix it. For our case, we will use the email address system.user@easternlogic.hk. In addition, you'll need to add a /token after the email address in order to use an API token, which is the recommended practice. So it will end up looking like this: system.user@easternlogic.hk/token. Alternatively, a password can be used for authentication, but we do not recommend as passwords are subject to change and can thus break the integration at a later time and create a difficult troubleshooting situation.

In the Password field, you'll need to add an API token. I recommend creating a new token for this integration. You can read more about Zendesk's API tokens here, or you can navigate to the Zendesk API page underneath the Apps and Integrations section > APIs heading of the admin page. The URL will look like https://{subdomain}.zendesk.com/admin/apps-integrations/apis/zendesk-api/settings/tokens, with the {subdomain} portion being replaced by your own account subdomain.

In the API page, click on Add API token to create a new API token to use with this integration.

Next, provide a description for your API token, such as Update Ticket Webhook. Then copy your token and paste it into the password field back in the create webhook page.

Once that's done, you should be ready to save your webhook. So go ahead and click the create webhook button at the bottom of the page.

The last page will be Step 3: Connect webhook. You can go ahead and click on Finish setup in the bottom right corner right away, and we will then proceed to create a trigger to fire the webhook.

Part 4: Creating the trigger(s)

For part 4, we will be creating a new trigger that will be using the webhook as an action to actually remove the ticket's sharing agreement. First, head over to the triggers page. You can do a search for trigger in the search bar, or manually navigate to it under the Objects and rules Section > Business rules heading. The URL for triggers will be under https://{subdomain}.zendesk.com/admin/objects-rules/rules/triggers, with {subdomain} being your account subdomain.

From here, click on Create Trigger.

You'll need to first provide a name for the new trigger, such as Update Decimal Field. You can optionally write a description to provide additional context about how the trigger is used. You'll also need to set a trigger category. You can choose from existing trigger categories or create a new one if needed.  We'll be using an existing one called Update Ticket.

Next, you'll need to determine the conditions for your trigger.  If you're unfamiliar with trigger conditions, we recommend first taking a look at Zendesk's guide to triggers here.

For our conditions, we will be firing when the ticket is updated and the custom field called Machine Type is set to the value Machine Type 1.  See screenshot below for reference:

In our case, we only want the trigger to fire if both of these conditions are met, so they must be created under the All section. Creating conditions under the Any section has a different outcome and can cause confusion for many new admins. For more information on All vs Any, please see this FAQ on Zendesk's Help Centre.

That being said, this trigger can be modified to fit your own requirements, either by using different conditions in the All section, by adding conditions to the any section, or even by cloning the trigger and using a different set of conditions.

Lastly, we will need to configure the actions section of the trigger. Click the Add action button, choose Notify by > Active webhook under the category, and choose the recently created Update Ticket Webhook as the value. You'll see the Endpoint URL, Description, and Method information appear below, as well as a place to input the payload.  This payload will need to follow a specific JSON format, which you can copy from below.

{
  "ticket": {
    "custom_fields": [
      {
        "id": 41678430443161,
        "value": "4.5"
      }
    ]
  }
}

The full trigger set up is shown below. Once you've set everything up, you can click on create trigger and then start testing it out.**

** Please be aware, that once you save the trigger it will be live, so it will start firing on any updated tickets that match the conditions. We highly recommend testing it out first by including a specific condition that will only be fulfilled by test tickets, such as the one we have added to check for tags Ticket > Tags > Contains at least one of the following > set_decimal_field

Then, you can test out the trigger by adding a set_decimal_field tag on to a ticket and then submit the update. 

Once the ticket is updated, you'll need to give Zendesk a few moments two to process the update, as it will occur in a separate event than the update you save by hitting the submit button.**

To make sure that the trigger and webhook fired correctly, you can open up the Event Log by using the clock icon in the upper middle portion of the ticket. Then, at or near the bottom of the log you should see an event called Message pushed to webhook and the name of the Trigger you created, which in our case is called Set Decimal Field.  If you do not see this message, then you may not have configured your trigger correctly or the conditions to fire the trigger may not have been met.

If you don't see this update, then it may be possible that there was an issue with the webhook. To troubleshoot this, you can go back to the Webhooks page in Zendesk, click on the webhook that you created, and then click to view the Activity log for that webhook.

In the Activity tab, you'll see a list of webhook invocations. A 200 OK means that the action was successful. If unsuccessful, you'll often see something in the 400 range.

For example, you can see that all of my webhook invocations have succeeded with a 200 OK Success message.

Unfortunately, this guide is unable to provide troubleshooting for all possible errors or provide examples for all the different use cases that could exist for this type of workflow, but it should provide a good starting point. Please feel free to leave comments below.