With an incoming webhook, you get a special unique URL that you can call from other applications to trigger changes in tickets. You manage incoming webhooks from Admin > Tickets > Webhooks.

When a webhook gets called, a filter is run to get a list of ticket matches. Then on each of those tickets, you define one or more triggers to operate on them.

Creating a webhook

Give your webhook a title so you remmeber what it's used for, and decide if your webhook will accept data or not. Currently only a JSON payload is supported. We'll go into more detail about using JSON payloads below.

The most important part of your webhook is the filter. In the filter, you define the broad criteria that must match for this webhook. Typically, you want to be as specific here as you can.

After you create your webhook, click the + icon next to its title in the list on the left to add a new trigger. You can add as many triggers as you want.

Triggers apply to all of the tickets that get matched based on your webhook filter. Since triggers themselves have criteria, you can effectively use the trigger criteria as a kind of "secondary filter". This can be useful in cases where a single webhook might need to apply to different tickets in slightly different ways.

Invoking a webhook

Click on the the webhook in the list on the left to open the webhook properties. Here you'll see a property "Webhook URL" which is the unique URL of this webhook. This is the URL you need to call to invoke the webhook.

For example, here's using cURL to invoke the webhook:

curl -XPOST http://example.com/api/v2/webhooks/DW0KGL4FTCRO217K/invocation
 copy

You can also send this to any third party application to use as well.

• Request type: GET or POST
• Request query string: Anything.
• Request payload: For POST requests, you may send a JSON payload.

Invoking the webhook with a query string or JSON payload

You can invoke the webhook with data passed in the query string, or with data passed in a JSON payload. This data can then be used in filters, trigger criteria, and also actions.

For example, here's a cURL request sending a query string and JSON data:

curl -XPOST \
  -H 'Content-Type: application/json'
  -d '{"myvalue": "example"}'
  http://example.com/api/v2/webhooks/DW0KGL4FTCRO217K/invocation?othervalue=otherexample
 copy

These values are now available in variables in the system:

• webhook.data contains the JSON payload. For example, webhook.data.myvalue will contain the value example.
• webhook.query contains data in the query string. For example, webhook.query.othervalue contains the value otherexample.

Using variables in filter or trigger criteria

To use a variable, you need to use a Twig template string. Twig is a templating system used by Deskpro and has many features including things like conditionals, looping, arithmatic, string operations, etc. But the most basic thing you can do with it is simply get the value of a variable.

For example, you can use a variable and compare it to the value of a custom field.

There's also a general-purpose trigger criteria to check a specific variable:

Using variables in trigger actions

There are certain trigger actions that allow Twig template execution. With these trigger actions, you can use the {{webhook.data.whatever}} variable syntax as demonstrated above. For example, setting a custom field value:

Note the "Use advanced formatting" checkbox is checked to enable Twig template execution.

Here's a list of actions that support the use of Twig expressions:

• Set custom field (with "Use advanced formatting")
• Set subject (with "Use advanced formatting")
• Add reply
• Add note