Webhooks

Overview

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.

PREREQUISITES:
  • Webhooks are available only to customers with paid subscriptions. To upgrade, contact Sitefinity Sales.
  • To create and manage webhooks, you need to be a Sitefinity Insight account administrator.

Manage webhooks

To create, view, or manage the properties of webhooks, log into Sitefinity Insight and navigate to Administration » Access & security » Webhooks.
The Webhooks window appears.

To create a webhook, click Create a webhook. For more information, see Create and edit a webhook below.

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 containing 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 (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 temporarily 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 in which you 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 undone.

Create and edit a webhook

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.

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, give a name of the webhook.
    This label is used to distinguish this webhook from other webhooks in the list of webhooks you have created.
  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 won’t execute it until you enable it.
  3. From Data center, choose the data center in which 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 Plus 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 which 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.

To configure how Sitefinity Insight will authenticate to the called URL, in Authentication type, select the type of authentication used. The following options are available:

  • Not specified
    Sitefinity Insight will perform an unauthenticated call.
  • Basic
    You must provide a username and password.
  • Raw
    Sitefinity Insight will include the exact content you specify in the HTTP header sent to the endpoint when executing the webhook.
  • Custom HTTP header
  • Enables you to manually specify key-value pairs which Sitefinity Insight will include in the HTTP header sent to the endpoint when executing the webhook.

To add additional HTTP headers to the request Sitefinity Insight will create when executing the webhook, expand the HTTP headers section and enter them as key-value pairs.

To confirm the changes, click Create this hook.

Sample payload

The following sample demonstrates the structure of the JSON payload in the requests which Sitefinity Insight generates.

Was this article helpful?