Insider Webhook
  • 27 Jun 2024
  • 7 Minutes to read

    Insider Webhook


      Article summary

      Webhook (Data Stream) is a feature that allows you to send real-time data to your endpoints. You can seamlessly integrate with Insider to receive events and attributes through webhooks.

      This feature enables you to transmit data to an endpoint as soon as it's collected by Insider, ensuring the timely delivery of valuable insights.

      Webhook offers two key functionalities:

      • Attribute Stream: This feature allows you to monitor specific user attributes and receive webhooks whenever there's a change. You can customize your webhook to stay informed about relevant user data in real time.
      • Event Stream: With Event Stream, you can track specific events and receive webhooks as they occur. Whenever an event is triggered by a user interaction, you can receive webhooks in real time.

      In this article, you can find answers to the following questions:

      Use Cases

      • Real-Time Data Updates: Integrate webhooks to ensure that all your tools and applications have access to the latest data in real time based on Insider triggers. For instance, automatically update customer profiles across multiple platforms whenever there's a change in their information, such as a new address or contact number.
      • Cross-Platform Communication: Enable seamless communication between different systems and platforms by using webhooks to send information to systems such as CRM tools or inventory management systems. For example, notify your CRM system whenever a new lead is generated on your website, ensuring that sales representatives can follow up promptly.
      • Automated Workflow Triggers: Utilize Insider webhooks to trigger automated workflows in response to specific user actions or events.

      How can I configure Insider Webhooks for my endpoint?

      To start sending your events and attributes for your endpoint, you can follow these steps:

      1. Navigate to External Platform Integrations > Webhook. Provide a name for your integration for easy identification and navigation later, then click Save to proceed.

      2. You will land on the Rules step. Here, you can select one or more Events or Attributes to trigger your integration in the tabs.

      3. After you select the first event type you want to trigger the data collection, you can see the events based on the type and select or deselect the ones you want to collect. You are also able to add other event types via the same section.

      You can also add event parameters.

      4. The Event Parameter section will be enabled after you select an event. You can select your events' parameters through the dropdown that you want to send your destination.

      5. You can select the additional attributes to be included in the data sent to the endpoint. If you want to include additional attributes while sending the event data to your destination, you can add them here. For example, if you are sending an email open event, you can also select the email address to be sent to your destination. This way, you can understand which email address opened which email campaign.

      6. In the Segmentation step, you can also select filter users in specific segments in Insider to send. The data is sent only if the users perform the selected event and meet the optional segment filter criteria. For example,using this section, you can send the user data who performs cart page view event and has a high Likelihood to Purchase value.

      7. You can continue with the Configure step which enables you to add your endpoint URL so that you can send your Insider data.

      In this step, you can also add headers and payload to send your endpoint.

      • If you want to send headers, check the “Enable Headers” checkbox, and add a header name and a value that you want to send as the header. Here, you can add multiple headers as you want to send.
      • Mark the “Enable Body” checkbox to configure the payload to be sent, and transform the data into your payload structure. You can add dynamic values to your payload in this section to include values of the events/event parameters/attributes values. You can simply copy and paste your API payload here and replace values with dynamic content to send payload per how the destination API requires it.

      8. After you configure your endpoint, headers, and body for your webhook, you can continue with the Launch step which is the last step to complete the integration. On this page, you can choose launch options as draft, active, or paused, and optionally add notes via the Notes field to enter additional information for your integration. The Draft option is selected by default. 

      • Before you start sending your webhooks, you should test your webhook through the Test Webhook button. After the test is successful you can activate sending webhooks to your endpoint.
      • You can add random values automatically for the dynamic values and click the Test button to send your data. After sending the data you can see the response status and your request details in the side modal to see if your request has been successfully sent.
      • If you see a successful HTTP response in the status, you can activate your integration and start sending data to your endpoint.

      9. After completing the steps, you successfully integrate Insider webhooks to your endpoint. This integration enables you to channel data seamlessly from Insider to your destination.

      What are the data structure and sample webhook?

      In any of the given cases above, Insider sends a payload to the given webhook URL with the following details:

      Attribute Stream

      ParameterDefinition
      attrsThe attributes object which contains the wanted attributes along with the subscribed attributes.
      hook_idThe ID of the subscribed webhook
      insider_idThe Insider ID/Profile ID of the user that is shared in the payload
      nameThe webhook name if applicable. You can name your webhooks, and share this name with Insider.
      partnerThis is your partner name. Navigate to Inone Settings > Account Preferences to copy your partner name. The partner name should be lowercase.
      timestampThe time when Insider receives the respective data that triggers the webhook (epoch time)
      triggersThe array that contains the case(s) that trigger the attribute stream

      Webhook Sample

      {
        "attrs": {
          "age": 20,
          "email_optin": false,
          "name": "John",
          "surname": "Doe"
        },
        "hook_id": 3,
        "insider_id": "a1b2c3d4e5f6",
        "name": "My attribute webhook",
        "partner": "poshstreet",
        "timestamp": 1623182670,
        "triggers": [
          {
            "current": {
              "value": "loyal"
            },
            "key": "membership",
            "next": {
              "value": "VIP"
            }
          }
        ]
      }

      Event Stream

      ParameterDefinition
      attrsThe attributes object which contains the wanted attributes along with the subscribed attributes.
      event_nameThe name of the subscribed event
      event_parametersThe event parameters of the subscribed event
      hook_idThe ID of the subscribed webhook
      insider_idThe Insider ID/Profile ID of the user that is shared in the payload
      nameThe webhook name if applicable. You can name your webhooks, and share this name with Insider.
      partnerThis is your partner name. Navigate to Inone Settings > Account Preferences to copy your partner name. The partner name should be lowercase.
      timestampThe time when Insider receives the respective data that triggers the webhook (epoch time)
      triggersThe array that contains the case(s) that triggers the attribute stream

      Webhook Sample

      {
        "attrs": {
          "age": 25,
          "email_optin": true,
          "name": "John",
          "sms_optin": false
        },
        "event_name": "purchase",
        "event_parameters": {
          "unit_price": 10,
          "url": "https://mybrand.com/blue-jeans"
        },
        "hook_id": 12,
        "insider_id": "1a2b3c4d5e6f",
        "name": "My event webhook",
        "partner": "mybrand",
        "timestamp": 1623187855,
        "triggers": [
          {
            "key": "url",
            "next": {
              "value": "https://mybrand.com/blue-jeans"
            }
          }
        ]
      }

      How can I throttle the webhook?

      You can limit the number of requests coming to your endpoint per second using Insider's throttling function.

      Endpoints for some services cannot handle many requests, and might not be able to receive and process them. You might also want to keep the number of requests coming to your endpoint from different services at a reasonable level for security reasons. 

      1. Go to External Integration Settings > Settings > Webhook Throttling.
      2. Click the Add a Webhook Endpoint button to add your endpoint. For every endpoint, you should enter the URL and the request size limit. You can add as many endpoints as you want.

        The request size should follow these rules:

        • It should be multipliers of 5.
        • It should be between 5-9999
        For each endpoint and limit, you should add them separately.
      3. After entering the URL and the request size, click the Save button to save your changes.

      The throttling settings will be automatically applied to the endpoint for all webhooks that you launch.

      Your title goes here
      Since throttling is endpoint-based, the request size limit you set is shared across all Insider InOne features, including all webhooks and Architect's Call APIs that use the same endpoint.

      How is webhook transmission managed?

      Insider has a retry mechanism designed to prevent webhooks from being transmitted in the event of errors or instantaneous problems with the endpoint. If a request encounters a timeout (set at 15 seconds), Insider triggers a retry process for the specific webhooks. However, if a response is received, no further retries are attempted.

      Insider's retry strategy includes a maximum of 10 attempts, following an exponential backoff duration pattern:

      • First Retry: 2 minutes after the initial attempt
      • Second Retry: 4 minutes after the first retry
      • Third Retry: 8 minutes after the second retry
      • Subsequent Retries: The waiting time between retries continues to double, adhering to the exponential backoff strategy.

      After the 10th retry, the system ceases any further attempts to re-send the request. 

      Your title goes here
      It's important to note that Insider applies this retry mechanism not only for timeouts but also for other error codes such as 429, 5xx, and more, ensuring a comprehensive and resilient approach to webhooks transmission.
      Your title goes here
      You can apply IP Restriction for webhooks payloads arriving at your endpoint. Insider sends webhooks from certain IP addresses. To view the IPs that Insider sends webhooks, navigate to Settings on the External Integrations page.
      Your title goes here
      This website doesn’t work with webhook functionality, we advise you to test your platform from your own endpoints or another website that has a similar functionality.

      Was this article helpful?

      What's Next
      ESC

      Eddy AI, facilitating knowledge discovery through conversational intelligence