<EntityName>Webhooks (REST API)

This article describes the Webhooks entity for the Autotask REST API. For the SOAP API equivalent of this webhook, refer to <EntityName>Webhook (SOAP API).

Overview

This entity describes the fields that populate to generate a webhook for an entity.

You can subscribe a callout to one of the callout types (PATCH, PUT or DELETE), or up to all three of them. When a callout subscribes to multiple types, they will share a single Webhook URL and Webhook ID.

BEFORE YOU BEGIN  Examples in this article may use the webservices[n].autotask.net placeholder. In such instances, substitute [n] for the zone of your user, as described in Autotask API zones and WSDL versions > Find your zone's API URL for the REST API or Autotask API zones and WSDL versions > Find your zone's WSDL file URL for SOAP API version 1.6.

Supported entities

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.

Entity details

You can also retrieve this information with the GET and POST REST API calls.

Entity Name: <EntityName>Webhook
Can Create:
Can Update:
Can Query:
Can Delete:
Can Have UDFs:  

The following child collection access URLs are available for this entity:

GET: /atservicesrest/v1.0/EntityName/{parentId}/ExcludedResources/

POST:

/atservicesrest/v1.0/EntityName/{parentId}/ExcludedResources/

DELETE:

/atservicesrest/v1.0/EntityName/{parentId}/ExcludedResources/{id}

GET:

/atservicesrest/v1.0/EntityName/{parentId}/Fields/

PUT:

/atservicesrest/v1.0/EntityName/{parentId}/Fields/

PATCH:

/atservicesrest/v1.0/EntityName/{parentId}/Fields

POST:

/atservicesrest/v1.0/EntityName/{parentId}/Fields/
DELETE: /atservicesrest/v1.0/EntityName/{parentId}/Fields/{id}

GET:

/atservicesrest/v1.0/EntityName/{parentId}/UdfFields/

PUT:

/atservicesrest/v1.0/EntityName/{parentId}/UdfFields/

PATCH:

/atservicesrest/v1.0/EntityName/{parentId}/UdfFields/

POST:

/atservicesrest/v1.0/EntityName/{parentId}/UdfFields/

DELETE:

/atservicesrest/v1.0/EntityName/{parentId}/UdfFields/{id}

Fields

Field Name

Label and Description

 Datatype Read Only Is Required Reference Name Is supported Webhook Field?

Deactivationurl

This field contains a separate URL that the API calls when the webhook (not the entity) is deleted or inactivated. This call will happen when the resource who created the webhook becomes deleted or deactivated.

 string (500)      

id

The data contained in this field is the webhook configuration ID. Webhooks receive an ID that is unique for the database and each entity.

EXAMPLE  The first webhook you create for the Account entity has ID = 1. Numbering is sequential.

 long    

IsActive

You can create webhooks with an Active setting of True or False. No callouts will occur if a webhook is inactive.

 boolean      

IsReady

This field is a read-only value that is set to true when the webhook is completely set up.

 boolean      

IsSubscribedToCreateEvents

The condition is true if this webhook triggers as the result of an entity's creation. The condition is blank or false if this webhook does not trigger as the result of an entity's creation.

 boolean        

IsSubscribedToDeleteEvents

True if this webhook is triggered by an entity being deleted. Blank or false if this webhook is not triggered by an entity being deleted.

 boolean        

IsSubscribedToUpdateEvents

The condition is true if this webhook triggers as the result of entity fields updating. The condition is blank or false if the webhook does not trigger as the result of an entity's fields updating.

 boolean        

Name

This field holds the name of the webhook. The name will appear in the subject line of error and notification emails. A best practice is to use a name that includes the integration name, the entity name and the event that will trigger the callout.

EXAMPLE  Marketo.Contact.Update

 string (50)      

NotificationEmailAddress

This value is an email address that receives notification of any error or alert, in addition to the email address associated with the API user authentication credentials.

 string (150)        

OwnerResourceID

This value is the Autotask resource ID of the API user. It is automatically tracked with the callout.

  • Each callout owner can only access and manage their own callouts in the API. The intent is to let an integration vendor create and manage their own callouts and not see any other callouts they don’t own.
  • Any notifications that go to the callout notification email address are also copied to the callout owner.
  • Callouts will continue to execute while the owner is locked out or a password is expired.
  • If the callout owner's user account is inactivated, all callouts owned by that username deactivate with a callout to the Deactivation URL.
 integer   Resource  

SecretKey

The recipient of the webhook call needs to confirm the legitimacy and integrity of the callout. You can do so by using a secret key known to both the sender and the recipient. Any combination of letters, number and symbols will work. We recommend a strong key with at least 10 digits.

Refer to Secret key and payload verification.

 string (64)      

SendThresholdExceededNotification

You can chose to received notification when the Webhook callout requests per hour per entity threshold has been exceeded.

Threshold exceeded is not an error condition, but it can deliver a warning if this callout flag's status is True and a notification email address is available to the callout.

  • A notification email would transmit once delivery is delayed, and again when callouts are caught up. The initial message will include the time delay.
  • The API will only send the second email if the first one was sent.
boolean      

WebhookGUID

GUID stands for Globally Unique Identifier. The value is a webhook ID that is unique across all Autotask databases.

 string (100)      

WebhookUrl

This value is the URL to which webhook callouts will be posted by the API. It is a web service that listens to outbound calls from Autotask.

 string (500)      

Sample request

Here is a sample REST request for a webhook that would fire if an account was modified:

POST https://webservices[n].autotask.net/atservicesrest/v1.0/CompanyWebhooks

{
"IsActive": true,
"DeactivationUrl": "https://wrkhbq676nwh8.d.samplecompany.net",
"IsSubscribedToUpdateEvents": true,
"Name": "myintegration.Accounts.Modify",
"SecretKey": "12345678",
"SendThresholdExceededNotification": false,
"WebhookUrl": "https://wrkhbq676nwh8.d.samplecompany.net"
}