This guide provides instructions for setting up Webhook Sync within the CRM Sync feature. This feature allows you to push data from Deskpro into an external system using webhooks.

Overview of Webhook Sync

Webhook Sync allows administrators to automate data transfer by sending requests to a specified URL whenever changes are made to users in Deskpro, such as user creation, updates, or deletions. This functionality is highly customizable, supporting a range of HTTP methods, authentication configurations, and custom headers, allowing integration with various external systems.

The Webhook Sync panel has four key tabs:

1. Create Users: Set up a webhook to trigger when new users are added.

2. Update Users: Set up a webhook for syncing changes when users are updated.

3. Delete Users: Configure a webhook for when users are removed.

4. Logs: View historical information regarding webhook activity.

To access CRM Sync, navigate to Admin > CRM > Crm Sync.

To create a new Webhook, click on the ‘Webhook’ option under ‘Add Sync’. This will add a new entry called ‘New Webhook Sync’.

Create Users Tab

1. Friendly Name: Provide a recognizable name for your webhook sync configuration. This will help differentiate between multiple syncs.

2. Authentication: Enter the username and password if authentication is required by the receiving endpoint.

3. Sync New User Webhook:

   • Unique ID Path: Specify the JSON path to the unique ID field in the response data. For instance, if the ID is returned as part of the JSON structure, use a path like $.id.

   NOTE: If this is not provided, Deskpro cannot continue to push updates to that configured CRM, beyond the initial creation.

   • Method: Choose the HTTP method for the webhook (e.g., POST, PUT).

   • Webhook URL: Provide the URL where the webhook should send data.

   • Headers: Define any additional headers required by the endpoint (e.g., Content-Type: application/json).

   • Data: Enter any custom payload data if needed. (see below for examples)

   • SSL Verification: Enable or disable SSL verification, depending on your server setup.

   • Timeout: Set the time (in seconds) that the system should wait for a response from the webhook.

Update Users Tab

• Toggle the option to enable syncing whenever a user record is updated in the system.

• Configure the following settings:

  • Method: Choose the HTTP method (typically PUT for updates).

  • Webhook URL: Provide the endpoint URL for updates.

  • Headers: Add necessary headers.

  • Data: Customize the payload data.

  • SSL Verification and Timeout as described above.

Delete Users Tab

• This tab works similarly to the Create Users and Update Users tabs, allowing you to specify the webhook URL and configure authentication and headers. It ensures the configured external system stays updated if user records are deleted.

Logs Tab

• The Logs tab provides visibility into past webhook events, allowing you to monitor success rates, identify issues, and gather relevant information.

Example Setup

To set up a webhook for syncing new users:

1. Go to the Create Users tab.

2. Enter a Friendly Name.

3. If the receiving server requires credentials, enter a Username and Password.

4. Set the Webhook URL to the desired endpoint.

5. Specify the Method as POST (typically used for create events, but choose the method relevant to your system).

6. Define any additional headers and data. These must be in JSON format.

7. Adjust SSL Verification and Timeout as needed.

8. Click Save.

Repeat similar steps in the Update Users and Delete Users tabs to handle updates and deletions, respectively.

Available Tokens and Example Data Payload

Available Tokens

The following tokens are available for use in the webhook configuration:

• {{ person.first_name }}

• {{ person.last_name}}

• {{ person.name }} : The first and last names combined.

• {{person.summary}}

• {{person.phone }}

• {{ person.organizations }} : A comma separated list of the organizations the user belongs to in Deskpro

• {{ person.contact.x }}: Replace x with the type: whatsapp, facebook, snapchat etc

• {{ person.last_logged_in }}

• {{ person.timezone }}

• {{ person.created_at}}: The timestamp when the user was created.

• {{ person.updated_at}}: The timestamp when the user was last updated.

These tokens can be used within headers or the data payload to dynamically insert user information.

Example Data Payload

Below is an example of a JSON data payload that might be used to sync user information:

{
  "first_name": "{{ person.first_name }}",
  "last_name": "{{ person.last_name }}",
  "name": "{{ person.name }}",
  "email": "{{ person.email }}",
  "created_at": "{{user.created_at}}",
  "updated_at": "{{user.updated_at}}"
}
 copy

This payload can be customized based on the requirements of the receiving system.