Webhooks

You use webhooks to integrate Sitefinity Insight with other systems and run tasks on these services when an event happens in your Sitefinity Insight data center. For example, you can send a notification to an app when a contact becomes a member of a specific Persona.

Webhooks let you subscribe to an event. When the event happens, the webhook is triggered, and Sitefinity Insight sends a POST request to an endpoint you have defined in the webhook with a JSON payload in the body. The payload contains information about the triggered event and any relevant additional details.

To view all webhooks, log into Sitefinity Insight and navigate to Administration » Access & security » Webhooks.
The Webhooks window appears.

You see a table containing all defined webhooks. For each webhook, you see the following information:

• In Webhook you see the name of the webhook.
  You set this name in the Label field when creating a webhook.
• In Data center you see the name of the data center that contains the webhook.
  The webhook can access data, such as Personas and Lead scorings, only in the specified data center.
• In Trigger you see what action triggers the execution of the webhook.
• In Payload, you can click Preview to see a JSON sample showing the format of the data which the webhook will send to the configured endpoint when it executes.
• In Successful runs in last 14 days and Failed runs in last 14 days, you see the total number of successful and failed runs of the webhook.

Each Webhook in the table has the  (Actions) button with the following commands:

• Edit properties
  You use it to edit the properties of the webhook. For more information, see Create and edit a webhook below.
• Deactivate / Activate
  You use it to suspend and resume the execution of the webhook.
• Preview payload
  You can see a JSON sample, showing the format of the data, which the webhook will send to the configured endpoint, when it executes.
• Runs in last 14 days
  Opens a window where you can see details about the execution history of the webhook.
  You see when the webhook was executed, how much time it took for the called endpoint to return a result, and whether the execution was successful.
  You can use the filter under the window title to select whether to see all, successful, or failed requests.
  All times are in UTC.
• Delete
  Deletes a webhook. This action cannot be reverted.

To create a webhook, perform the following:

1. Navigate to Administration » Access & security » Webhooks.
2. Click Create a webhook.
   The Create a webhook window appears, where you set the webhook properties..

To edit existing webhook properties, perform the following:

1. Navigate to Administration » Access & security » Webhooks.
2. Click Create a webhook.
   The Create a webhook window appears.

To set the webhook properties, perform the following:

1. In the Label field, enter a name for the webhook.
   This label is used to distinguish this webhook from other webhooks in the list.
2. To immediately activate the new webhook, set its Status toggle to Active.
   If you set the webhook status to Inactive, the webhook will be configured and preserved, but Sitefinity Insight will not execute it, until you enable it.
3. In Data center, select the data center where the webhook will be created.
   The webhook can access data, such as Personas and Lead scorings, only in the specified data center.
4. In Trigger, select when the webhook will trigger.
   If you select Persona or Lead scoring related trigger, you can use  to specify additional details about the trigger.
   For example, the stage of the lead scoring or a specific Persona to trigger the webhook.
5. In Send data to URL, enter the full URL of the endpoint that Sitefinity Insight will use to send the data when the webhook triggers.
   Click Payload preview to see a sample JSON for the trigger you have selected.
   NOTE: You must use a HTTPS endpoint and you cannot use localhost as endpoint.

6. To configure how Sitefinity Insight authenticates to the called URL, in Authentication type, select one of the following authentication types:

   • Not specified
     Sitefinity Insight performs an unauthenticated call.
   • Basic
     You must provide a username and password.
   • Raw
     Sitefinity Insight includes the exact content that you specified in the HTTP header, which is sent to the endpoint when executing the webhook.
   • Custom HTTP header
     Enables you to manually specify key-value pairs that Sitefinity Insight includes in the HTTP header, which is sent to the endpoint during the webhook execution.
7. To add more HTTP headers to the request, which Sitefinity Insight creates during the webhook execution, expand the HTTP headers section and enter them as key-value pairs.
8. Click Create this hook.

The following samples demonstrate the structure of the JSON payload in the requests which Sitefinity Insight generates for all supported events.

Became contact event

Contact updated event

Persona scoring passed threshold event

Persona scoring exited threshold event

Lead scoring passed threshold event

Lead scoring exited threshold event