Webhooks Overview

Webhooks offer a versatile and efficient solution for real-time communication and integration between various applications. They provide a way for applications to communicate and share information without the need for constant polling or manual intervention.

The process typically starts with the application that wants to carry out notifications (the "sender" or "source") and then setting up a webhook URL in the recipient application (the "receiver" or "destination"). The webhook URL acts as an endpoint to which the sender will send HTTP requests. When the specified event or trigger occurs in the sender application, it will initiate an HTTP request to the webhook URL provided by the receiver. This request contains relevant data or information related to the event. The receiver application can then process this data, perform specific actions, or trigger further processes based on the received information. 

Outgoing Webhooks 

Outgoing webhooks are a mechanism from Act-On to send real-time notifications and data to another system in response to specific Act-On events. Instead of waiting for a client or external system to request information, the Act-On will initiate the communication by sending a webhook to a predefined endpoint URL. This outgoing webhook carries data related to the event that occurred.

Act-On Outgoing Webhook Event Types

Generic Event Types

The following tables list events that accounts can subscribe to and connect to any 3rd party platform

automated-program.started

This webhook is triggered when an Automated Program is started.

Field Name	Title	Data Type	Required	OBJECT
description	Automated Program description	string	Optional	{ "description": "Program Description Example", "entryType": "Manual", "link": "https://example.actonsoftware.com/app/automation/programs/##-####/program-performance", "name": "Program Name Example", "programSchedule": "Pending contacts added manually", "startedTime": 1686597624671, "waitingCount": 0 }
entrytype	Automated Program entry type	string	Optional
link	Automated Program program link	string	Optional
name	Automated Program name	string	Required
programSchedule	Automated Program program schedule	string	Optional
startedTime	The time that the Automated Program started	integer	Optional
waitingCount	Automated Program waiting count	number	Optional

automated-program.stopped

This webhook is triggered when an Automated Program is stopped.

Field Name	Title	Data Type	Required	OBJECT
description	Automated Program description	string	Optional	{ "description": "Program Description Example", "entryType": "Manual", "link": "https://example.actonsoftware.com/app/automation/programs/##-####/program-performance", "name": "Program Name Example", "programSchedule": "Pending contacts added manually", "stoppedTime": 1686597624671, "waitingCount": 0 }
entrytype	Automated Program entry type	string	Optional
link	Automated Program program link	string	Optional
name	Automated Program name	string	Required
programSchedule	Automated Program program schedule	string	Optional
stoppedTime	The time that the Automated Program stopped	integer	Optional
waitingCount	Automated Program waiting count	number	Optional

contact-bounce.hard

When a contact is added to the hard bounce list, it triggers a webhook with this object as its payload.

Field Name	Title	Data Type	Required	OBJECT
Diagnostic	The SMTP error code for this bounce	string	Optional	{ "bounceDiagnostic": "User upload", "categoryReason": "User", "email": "[e-mail]", "isHardBounce": true "msgId": "s-002e-2303", "timestamp": 1689559644 }
categoryReason	Why the message failed to send	string	Required
email	The email from the contact who joined the hard bounce list	string	Required
isHardBounce	A boolean value indicating if the contact joined the hard bounce list. Should always be true for this event.	boolean	Required
msgId	The message ID	string	Required
timestamp	A timestamp of the moment the contact hard bounced	integer	Required

contact-bounce.soft

When a contact is added to the soft bounce list, it triggers a webhook with this object as its payload.

Field Name	Title	Data Type	Required	OBJECT
email	The email from the contact who joined the hard bounce list	string	Required	{ "email": "[e-mail]", "isHardBounce": true }
isHardBounce	A boolean value indicating if the contact joined the hard bounce list. Should always be true for this event	boolean	Required

contact-email.marked-as-spam

This webhook is triggered every time a contact marks an email as spam.

Field Name	Title	Data Type	Required	OBJECT
email	The email from the contact that marked an email as spam	string	Required	{ "email": "[e-mail]", "msgId": "s-002e-2303", "recId": "l-0001:14", "srcId": "l-0001", "timestamp": 1689343863 }
msgId	The message ID	string	Required
recId	The contact ID	string	Required
srcId	The source ID	string	Required
timestamp	A timestamp of the moment the contact marked an email as spam	integer	Required

contact-opt.global-opt-in

When a contact opts in to all email communication, it triggers a webhook with this object as its payload.

Field Name	Title	Data Type	Required	OBJECT
email	The email from the contact who opted in	string	Required	{ "email": "[e-mail]", "hasOptedOut": false "timestamp": 1689559644 }
hasOptedOut	A boolean value indicating if the contact has opted out. Should always be false for this event	boolean	Required
timestamp	A timestamp of the moment the contact opted in	integer	Required

contact-opt.global-opt-out

When a contact opts out from all email communication, it triggers a webhook with this object as its payload.

Field Name	Title	Data Type	Required	OBJECT
email	The email from the contact who opted out	string	Required	{ "email": "[e-mail]", "hasOptedOut": true "timestamp": 1689559644 }
hasOptedOut	A boolean value indicating if the contact has opted out. Should always be true for this event	boolean	Required
timestamp	A timestamp of the moment the contact opted out	integer	Required

crm.connected

This webhook is triggered every time a user connects to a CRM.

Field Name	Title	Data Type	Required	OBJECT
crmDisplayName	The name of the CRM the user was connected to	string	Required	{ "crmDisplayName": "Salesforce", "detail": "Successful connection", "timestamp": 1689343863 }
detail	The details of the CRM connection	string	Required
timestamp	A timestamp of when the CRM connection occurred	integer	Required

crm.disconnected

This webhook is triggered every time a user disconnects from a CRM.

Field Name	Title	Data Type	Required	OBJECT
crmDisplayName	The name of the CRM the user was connected to	string	Required	{ "crmDisplayName": "Salesforce", "detail": "Fail connection due to credential", "timestamp": 1689343863 }
detail	The details of the CRM connection	string	Required
timestamp	A timestamp of when the CRM disconnection occurred	integer	Required

email-message.scheduled

This webhook is triggered every time a message is scheduled.

Field Name	Title	Data Type	Required	OBJECT
accountId	The message's Account ID	integer	Required	{ "accountId": "4", "accountName": "Name", "creatorId": "5", "creatorName": "Creator's Name", "messageId": "s-002e-2303", "numTargetedRecipients": "2", "previewText": "preview text", "scheduledTimeZone": "America/Sao_Paulo", "scheduledTimestamp": "1694004008962", "schedulingOfEmail": "1694003951450", "selectedSender": "FirstName LastName|[e-mail]|user", "subject": "subject", "title": "Title" }
accountName	The message's Account Name	string	Required
creatorId	The creator ID	integer	Required
creatorName	The creator name	string	Required
messageId	The message ID	string	Required
numTargetedRecipients	The total number of recipients	integer	Required
previewText	The message preview text	string	Required
scheduledTimeZone	The timezone in which the message was scheduled	string	Required
scheduledTimestamp	A timestamp of when the message was scheduled	integer	Required
schedulingOfEmail	A timestamp of when the scheduled message was created	string	Required
selectedSender	Sender's name and email	string	Required
subject	The message subject	string	Required
title	The message title	string	Required

form.submitted

When a Form is submitted, it triggers a webhook with this object as its payload.

Note: This webhook requires an additional setup. You need to identify the forms that should trigger a webhook event on submission by configuring the form. See here for details.

Field Name	Title	Data Type	Required	OBJECT
browser	The browser from the registration was submitted	string	Optional	{ "browser": , "campaignSource": , "contact": { "email": "[e-mail]", "firstName": "John", "lastName": "Doe" }, "cookieId": "0076d7", "formId": "e23a97da-3346-4c32-9bc9-15ab0dc9ca8a", "formName": "Form name", "referrer": "referrer example", "submissionTime": 1234567890 }
campaignSource	The campaign source of the Form where the registration was submitted	string	Optional
contact		object	Required
cookieId	The cookie ID of the form where the registration was submitted	string	Required
formId	The ID of the form where the registration was submitted.	string	Required
formName	The name of the Form where the registration was submitted	string	Required
referrer	The referrer of the Form where the registration was submitted	string	Optional
submissionTime	The submission time when the registration was submitted	integer	Optional

subscription-category.added

This webhook is triggered every time a contact adds a new subscription category.

Field Name	Title	Data Type	Required	OBJECT
checked	If the user added a category	boolean	Required	{ "checked": true, "description": "News about our best offers", "id": "1", "name": "Discounts", "timestamp": 1689343863 }
description	The description of the category	string	Required
id	The ID of the category from Act-On	string	Required
name	The name of the category	string	Required
timestamp	A timestamp of when the category was added	integer	Required

subscription-category.deleted

This webhook is triggered every time a contact deletes a subscription category.

Field Name	Title	Data Type	Required	OBJECT
checked	If the user deleted a category	boolean	Required	{ "checked": true, "description": "News about our best offers", "id": "1", "name": "Discounts", "timestamp": 1689343863 }
description	The description of the category	string	Required
id	The ID of the category from Act-On	string	Required
name	The name of the category	string	Required
timestamp	A timestamp of when the category was deleted	integer	Required

subscription-category.opt-in

This webhook is triggered whenever a contact opts in to a subscription category.

Field Name	Title	Data Type	Required	OBJECT
categoryChecked	Indicates if the contact is opted into the category	boolean	Required	{  "categoryChecked": true, "categoryDescription": "News about our best offers",  "categoryId": "1", "categoryName": "Discounts",  "email": "[e-mail]", "timestamp": 1689343863  }
categoryDescription	Description of the category	string	Required
categoryId	Unique ID of the category	string	Required
categoryName	The name of the category	string	Required
email	The email from the contact that opted into the category	string	Required
timestamp	A timestamp of the moment in which the opt-in happened.	integer	Required

subscription-category.opt-out

This webhook is triggered whenever a contact opts out from a subscription category.

Field Name	Title	Data Type	Required	OBJECT
categoryChecked	Indicates if the contact is opted into the category	boolean	Required	{  "categoryChecked": false, "categoryDescription": "News about our best offers",  "categoryId": "1", "categoryName": "Discounts",  "email": "[e-mail]", "timestamp": 1689343863  }
categoryDescription	Description of the category	string	Required
categoryId	Unique ID of the category	string	Required
categoryName	The name of the category	string	Required
email	The email from the contact that opted out of the category	string	Required
timestamp	A timestamp of the moment in which the opt-out happened.	integer	Required

subscription-category.updated

This webhook is triggered every time a contact updates a subscription category.

Field Name	Title	Data Type	Required	OBJECT
checked	If the contact updated a category	boolean	Required	{  "checked": true, "description": "News about our best offers",  "id": "1", "name": "Discounts",  "timestamp": 1689343863  }
description	Description of the category	string	Required
id	Unique ID of the category	string	Required
name	The name of the category	string	Required
timestamp	A timestamp of the moment in which the opt-out happened.	integer	Required

Preconfigured Event Types

Act-on will be providing platform-specific pre-configured events for certain use cases to facilitate the integration setup process with the webhook.

Platform	Event Type	Object
Slack	automated-program.started.slack	{ "text": "The following Automated Program has started.\n\n*Program Name:* Program Name Example \n*Program Description:* Program Description Example \n*Started on:* mm-dd-yyyy \n*People Entering Program:* 0 \n*Program Entry Type:* Manual \n*Schedule:* Pending contacts added manually \n*Link to Program:* https://example.actonsoftware.com/app/automation/programs/##-####/program-performance" }
Slack	automated-program.stopped.slack	{ "text": "The following Automated Program has stopped.\n\n*Program Name:* Program Name Example \n*Program Description:* Program Description Example \n*Stopped on:* mm-dd-yyyy \n*People Entering Program:* 0 \n*Program Entry Type:* Manual \n*Schedule:* Pending contacts added manually \n*Link to Program:* https://example.actonsoftware.com/app/automation/programs/##-####/program-performance" }
Teams	automated-program.started.teams	{ "text": "**Program Name:** Program Name Example \n**Program Description:** Program Description Example \n**Started on:** mm-dd-yyyy \n**People Entering Program:** 0 \n**Program Entry Type:** Manual \n**Schedule:** Pending contacts added manually \n**Link to Program:** https://example.actonsoftware.com/app/automation/programs/##-####/program-performance", "title": "The following Automated Program has started." }
Teams	automated-program.stopped.teams	{ "text": "**Program Name:** Program Name Example \n**Program Description:** Program Description Example \n**Started on:** mm-dd-yyyy \n**People Entering Program:** 0 \n**Program Entry Type:** Manual \n**Schedule:** Pending contacts added manually \n**Link to Program:** https://example.actonsoftware.com/app/automation/programs/##-####/program-performance", "title": "The following Automated Program has started." }

Authentication

Act-On will send a payload with a signature. Customers can validate the signature using the secret key provided for the endpoint and the payload received by generating an HMAC SHA-256 hash. In addition, custom headers can be added to authenticate the webhook based on the destination platform’s requirements. See here how to create and manage an outgoing webhook.

Incoming Webhooks

Incoming webhooks in Act-On are special endpoint URLs that act as communication channels between a third party which is triggering the Outgoing Webhook and Act-On. The purpose of the incoming webhook is to receive the message, aka payload, parse it, and take action based on it. The communication channels can be used for any type of use case; from updating Act-On databases to triggering specific processes in Act-On. Currently, we support channels for All Contacts and Custom Touch Point Behaviors. See here how to create, validate, and manage incoming webhooks.