Deskpro can use a web hook action (as part of a trigger, escalation or SLA) to interact with external services that accept commands using the web’s HTTP protocol.

Many services offer HTTP APIs, so this provides a relatively simple way to have Deskpro interact with other software you use (or custom software your organization has developed). For example, if a suitable API is available, you could post a warning on your intranet when a ticket fails an SLA.

When the action runs, it sends an HTTP request using the HTTP method you specify from POST, GET, PUT and DELETE. A POST, PUT or DELETE request includes a representation of the relevant ticket in the request parameters. This enables the external service to use the information about the ticket. A GET request has an empty body.

See this Knowledgebase article for an example of the format.

Note that this option can only send data from Deskpro to an external service. If you want an external service to change data within your helpdesk, you will need to use the Deskpro API.

To create a web hook:

Select the Call Web Hook action type within a trigger, escalation, SLA or macro.

Fill in the requested settings:

• URL means the URL where the external service accepts requests
• username and password to authenticate with the external service (if required)
• custom headers and data that will be included in the request (consult the documentation for the API/service you are using to select appropriate values for these)
• timeout specifies how long in seconds Deskpro will wait for the HTTP request to be acknowledged by the external service before giving up.

Click Save.

Whenever the action runs, Deskpro will make the specified HTTP request.

To help with debugging, you can view the HTTP requests that an action is sending by using a tool such as RequestBin, to collect and display requests in a readable way. You will need to temporarily change the URL for the action to the address provided by RequestBin.

Using custom headers and data

You can send custom values in the HTTP headers by entering them in the Custom Headers field of the web hook action.

The format is:

X-Custom-Header: value
X-Custom-Header2: value2
 copy

You can also send custom data in the body of the post, to be included in the custom_data: parameter.

You can use variables to send particular properties of the ticket that triggered the action in the custom headers or data.

For example, when creating the web hook action you could enter a Custom header of:

X-Deskpro-TicketId: {{ ticket.id }}
 copy

Then the HTTP headers sent due to an action on the ticket with ID 5 would include “X-Deskpro-TicketId: 5”.

The syntax and possible values are the same as Deskpro uses for snippets in the agent interface and when sending messages with actions.

Ticket variables

{{ ticket.subject }}
 copy

Ticket subject.

{{ ticket.department.title }}
 copy

Ticket department name.

{{ ticket.product.title }}
 copy

Ticket product.

{{ ticket.category.title }}
 copy

Ticket category.

{{ ticket.workflow.title }}
 copy

Ticket workflow.

{{ ticket.priority.title }}
 copy

Ticket priority.

{{ ticket.id }}
 copy

Ticket ID.

{{ ticket.fieldX }}
 copy

Value of a custom ticket field (replace X with the field ID number).

{{ ticket.ref }}
 copy

Ticket ref code.

{{ ticket.date_created }}
 copy

Time and date ticket was created e.g. 2014-03-14 11:38:17.

User variables

.. describe:: {{ ticket.person.display_name }}
 copy

User’s name.

{{ ticket.person.primary_email.email }}
 copy

User’s email.

{{ ticket.person.organization.name }}
 copy

User’s organization.

{{ ticket.person.organization_position }}
 copy

User’s position in organization.

{{ ticket.person.fieldX }}
 copy

Value of a custom user field (replace X with the field ID number).

Agent variables

{{ ticket.agent.display_name }}
 copy

Agent name (or override name if set).

{{ ticket.agent.primary_email.email }}
 copy

Agent primary email.

{{ ticket.agent_team.name }}
 copy

Agent primary team.