Webhooks

Webhooks are an efficient way to exchange information between applications.

Traditional API calls provide information in response to a query. To get updated information via an API call, you have to keep polling the application.

EXAMPLE  "Were any new companies added to my database since the last query?
Were any new companies added to my database since the last query?
Were any new companies added to my database since the last query?..."

Imagine that only 2% of the time, you receive a positive answer. All that network traffic, so little to show for it.

Webhooks, on the other hand, work on a "Don't call me, I'll call you if I have something new" basis. The server-side application calls the client-side application (by invoking a client-provided webhook URL) any time that the server-side has something new to report to the client. When an event happens, a notification routes to any registered subscribers in the form of an HTTP POST request. The information (or 'payload') arrives in JSON format on port 443.

EXAMPLE  "A user added a new company to your database, and here is the company name, company type, address, phone number, and website."

You can use webhooks to synchronize companies and contacts in Autotask with applications that also track company and contact information, including:

• Lead generation software
• CRM platforms
• Quoting systems
• Accounting software

In all of these cases, accounts and contacts you create or update in Autotask can synchronize with the target application in near-real-time. The Company/ContactWebhookExcludeResource entity can stop resources within Autotask from triggering webhooks. You can also use external ID fields or user-defined reference fields for reliable data mapping. You can always include them in the payload, even if you have not updated them.

Autotask webhooks can and should be created by partners and vendors who are building integrations with Autotask, and vendors who are building connectors to middleware products.

Using webhooks instead of regular API calls can lead to a significant reduction in the number of inbound calls against our API platform, which will increase performance for all API users. But there are significant advantages for the integration developer as well. Webhooks allow you to design applications differently than a polling application, and you can often implement them with less coding. Webhooks for actions like creating and updating can be specific to that action. With the polling approach, code must handle checking for a large number of records, often caching data and comparing fields to determine what has changed. With webhooks, developers can build integrations faster and for a lower cost.

Additional advantages:

• Near real-time notifications: The speed with which you can discover that a change occurred is currently limited by the polling time interval. Webhooks provide almost instantaneous notification of changes.
• Reduced risk of hitting the API threshold: Your risk of reaching the API maximum call threshold becomes reduced without the need to do polling.

Webhooks are created and managed entirely from the Autotask API.

We provide a read-only page that allows administrators to view all currently existing webhooks for your database. Refer to Viewing the list of webhooks in your database.

The following Autotask entities currently support webhooks:

• Companies (Accounts)
• Contacts
• Assets (Configuration Items)
• Tickets, including tickets created in Taskfire (REST only)
• Ticket Notes, including ticket notes created in Taskfire (REST only)

We will continuously add webhook support to additional entities.

The following events can trigger a webhook callout:

• Create: All create events will trigger a callout. You can implement callouts as Active or Inactive.
• Update: Each update where at least one callout field or callout UDF has changed will trigger a callout. Every time you save a database record is a separate triggering event. All settings that are not read-only will update. Only the owner (the resource who created the webhook) can make an update callout.
• Delete: Each deletion of an entity record will fire an event. Only the owner (the resource who created the webhook) can make a delete callout.
• Deactivate: Each deactivation of a callout will fire an event.

IMPORTANT  The above actions are those to which you can subscribe via ContactWebhooks and CompanyWebhooks (Create, Update, Delete). Deactivation does not work the same way, although it will trigger a callout.

EXAMPLE  You update a field that is configured to trigger a webhook callout, but something is wrong with the callout URL, and the action can't complete. The retry logic activates behind the scenes. If it continues to fail, it will send a callout to your deactivation URL. This behavior differs from a situation in which the user changes the phone number of a contact, in turn activating a webhook.

To create webhooks, you must use version 1.6 or above of the Autotask SOAP API or version 1.0 or above of the Autotask REST API. Integration developers must have an API only security level.

NOTE  The resource's security and Line of Business constraints do apply to callouts. If the owner resource does not have access to a data record, the callout will not fire for those records.

To enable your integration developers to create webhooks, you must complete two setup tasks:

1. Add a security level that allows the creation of webhooks

IMPORTANT  For security reasons, the ability to create webhooks is disabled by default for all security levels. Webhooks can send information from your Autotask database to an external service. Autotask administrators should grant this permission selectively and sparingly, rather than assigning it by default to an entire group of security levels.

To take advantage of webhooks, you must create an API only security level and enable the setting:

1. Go to Admin > Company Settings & Users > Resources/Users (HR) > Security > Security Levels.
2. Right-click the API User (system) (API-only) security level, or any other one with a license type of API User and select Copy.
3. Expand the Other section.
4. Select the Can create WebHooks check box and enter the maximum number of webhooks users with this security level will be allowed to create.
   
   

NOTE  A best practice is to create a separate security level and a separate resource for each integration. Doing so allows you to tailor data access, impersonation rights, and webhook permissions to each integration, enhancing overall application security.

2. Assign the new security level to an integration developer

Once you have set up an API user security level with webhooks permission, assign it to the integration developer who will be creating webhooks.

IMPORTANT  IMPORTANT SECURITY CONSTRAINT: Webhooks will only fire if the webhook owner has the required entity and object-level permissions, Protected Data Permissions, or access to the Line of Business with which the entity is associated. If their permissions would prevent them from performing an action, any webhooks they created won't fire in response. Make sure that the security level settings match the requirements. As an example, a delete callout will only fire if the owner has delete permissions for the account.