Configuring API Webhooks


This is not available in the cloud as of now, but coming soon.

During installation, the Act installer will configure the Webhook opportunityService. It will create or connect to existing webhook registration database.


Creating a new webhook


When creating a webhook you will need to provide the following in the request:


Monitor This indicates the entity that will be monitored for notifications. The following list of supported entities: Activities, Companies, Contacts, Fields, Groups, History, Opportunities, and Products.
FYI: Because metadata is cached, the Fields webhooks will not send notifications, if created/updated outside of the API.
TriggerEvent This indicates the event that will trigger the webhook notification. The following list of supported triggers: Created, Updated, and Alarms.
QueryOption Any valid OData query can be used to target or filter the webhook to a specific task and/or request for more information in the response message. This is an optional parameter, but if left null|blank it will return these default properties: id, created, and edited) | For Alarms: id, startTime, and leadMinutes.

FYI: It is very important that you do not include the default properties in the query option, it may cause the webhook from firing correctly..

See Query Options section below.
CallbackUrl The endpoint that the webhook response will be posted.
CallbackToken An symmetric key that will be added to the Authorization header.
Description A simple description of what|why this webhook was created.

Configuration

The Act.Webhook.Notifications opportunityService has a few configuration settings that you might need to be aware of. Here is a list that that you might be interested in:

PollingIntervalSeconds: This defines the number of seconds elapsed between each polling interval. The default is 900 seconds (15 minutes).

PollingRetryIntervalSeconds: This defines the number of seconds elapsed between retries. Default is 120 seconds (2 minutes).

RetryAttempts: This is the number of attempts that a failed webhook will be retried before the webhook is suspended. The default retry attempts is 3.


Activity Alarms

Activity alarms work a little differently that the other webhooks. The Alarms are pulled into a queue on the polling interval cycle, but are not broadcast until the actual alarm sounds.


Webhook Samples


If the call back site does not have a valid certificate assigned, register the callbackUrl using the http protocol.

{
	"monitor": "Activities",
	"triggerEvent": "Created",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/created-activities/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created activity."
}

This also applies to the Act! Web API. If it is not hosted with a validate certificate, make sure you GET a token and POST the webhook registration to the Act! Web API, using a http protocol and not https. 

	"GET:  http://localhost/act.web.api/authorize".
	"POST: http://localhost/act.web.api/api/webhooks".

Activities


To create an activity webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Activities",
	"triggerEvent": "Created",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/created-activities/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created activity."
}

To create an activity webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Activities",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-activities/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified activity."
}

To create an activity webhook that sends notifications when an activity alarm is sounding.


POST: api/webhooks

{
	"monitor": "Activities",
	"triggerEvent": "Alarms",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/alarms-activities/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture activity with alarms about to sound."
}


Companies


To create a company webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Companies",
	"triggerEvent": "Created",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/created-companies/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created companies."
}

To create a company webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Companies",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-companies/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified companies."
}

Contacts


To create a contact webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Contacts",
	"triggerEvent": "Created",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/created-contacts/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created contacts."
}

To create a contact webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Contacts",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-contacts/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified contacts."
}

Fields


To create a fields webhook that sends notifications when a new column (field) is created on a table.


POST: api/webhooks

{
	"monitor": "Fields",
	"triggerEvent": "Created",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/created-fields/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture when a new database column is created."
}

To create a fields webhook that sends notifications when a column (field) is updated on a table.


POST: api/webhooks

{
	"monitor": "Fields",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-fields/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified database columns."
}

Groups


To create a group webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Groups",
	"triggerEvent": "Created",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/created-groups/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created groups."
}

To create a group webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Groups",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-groups/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified groups."
}

Histories


To create a history webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "History",
	"triggerEvent": "Created",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/created-histories/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created history items."
}

To create a history webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "History",
	"triggerEvent": "Updated",
	"queryOption": null,
  	"callbackUrl": "http://localhost:17282/api/updated-histories/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified history items."
}

Opportunities


To create a opportunity webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Opportunities",
	"triggerEvent": "Created",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/created-opportunities/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created opportunities."
}

To create a opportunity webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Opportunities",
	"triggerEvent": "Updated",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/updated-opportunities/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified opportunities."
}

Products


To create a product webhook that sends notifications when this entity is created.


POST: api/webhooks

{
	"monitor": "Products",
	"triggerEvent": "Created",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/created-products/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created products."
}

To create a product webhook that sends notifications when this entity is updated.


POST: api/webhooks

{
	"monitor": "Products",
	"triggerEvent": "Updated",
	"queryOption": null,
	"callbackUrl": "http://localhost:17282/api/updated-products/callback",
	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture modified products."
}

Query Options


The query option can be used to customize your webhook response. To configure this you add an OData query to your request. This sample request will send a webhook when any contact is created within Arizona. Start your query option with a $ and not a ?.


Remember to always test your OData query before using it in a webhook! Invalid OData queries will not fail, but give you unexpected results.


{
	"monitor": "Contacts",
	"triggerEvent": "Created",
	"queryOption": "$select=jobTitle,emailAddress,fullName,company&$filter=(businessAddress/state eq 'AZ')",
  	"callbackUrl": "http://localhost:17282/api/created-contacts/callback",
   	"callbackToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ0wNS0zMVQyMDozODowMS41OTI1MTcxWiJ9",
	"description": "Webhook to capture newly created contacts."
}
RESPONSE 

[
    {
        "id": "a79d2083-0485-4353-a4c4-bf9d0c0821fc",
        "created": "2018-05-29T06:12:44-07:00",
        "edited": "2018-05-29T06:12:44-07:00",
        "company": "Swiftpage",
        "fullName": "Stephen Burton",
        "emailAddress": "stephen.burton@swiftpage.com",
        "jobTitle": "Senior Web API Engineer"
    }
]