How to use Webhooks

Webhooks are a way to instantly receive information from your widgets as soon as it’s submitted. You specify the URL you want to receive the data to and GetSiteControl will POST to that URL whenever a widget is filled out on your website. Webhooks allow you to receive real time data from your widgets. How you use it is up to you. You can enable webhooks for Subscribe, Survey and Contact widgets.

Submit URL

First, you need to specify the URL you want to receive the data from the widget to. Open your GetSiteControl dashboard, click to Edit the necessary widget, switch to the Integrations tab and check the Enable webhooks option.

null

Enter the URL you want GetSiteControl to make HTTP POST requests to and save the changes.

Now when webhooks are enabled all new submissions will be automatically POSTed to the specified URL.

POST notification format

Webhook notifications are sent via HTTP POST request, and the request body containing the response data is in JSON format. Below is an example request that contains all possible field types.

{
  "id": 33,
  "type": "form_response",
  "date": "2016-07-28T10:18:28.869Z",
  "widget": {
    "id": 5,
    "type": "contact",
    "name": "Contact widget"
  },
  "page": "http://example.com/page.html",
  "ip": "65.55.37.104",
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "Washington",
    "state_code": "WA",
    "district": null,
    "city": "Redmond",
    "postal_code": "98052",
    "latitude": 47.674,
    "longitude": -122.1215,
    "locale": "en",
    "timezone": "America/Los_Angeles"
  },
  "lang": "en-US",
  "browser": "Chrome",
  "os": "Linux",
  "platform": "Desktop",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.106 Safari/537.36",
  "context": {
    "utm_campaign": "Search US",
    "utm_medium": "cpc",
    "utm_content": "Buy best car",
    "utm_source": "google.com",
    "utm_term": null,
    "returning": true,
    "source": null
  },
  "custom": {
    "tariff": "Pro",
    "accountId": 8756
  },
  "response": [
    {
      "field": {
        "type": "email",
        "name": "email",
        "label": "Email"
      },
      "value": "user@example.com"
    },
    {
      "field": {
        "type": "text",
        "name": "q188567607",
        "label": "Name"
      },
      "value": "John Smith"
    },
    {
      "field": {
        "type": "textarea",
        "name": "message",
        "label": "Message"
      },
      "value": "Hello, It's beautiful!"
    },
    {
      "field": {
        "name": "q450292699",
        "label": "Select one",
        "type": "radio",
        "options": [
          {
            "comment": true,
            "name": "opt173445031",
            "label": "Option 1"
          },
          {
            "name": "opt230309546",
            "label": "Option 2"
          }
        ]
      },
      "value": [
        {
          "comment": "My comment",
          "name": "opt173445031",
          "label": "Option 1"
        }
      ]
    },
    {
      "field": {
        "name": "q309498997",
        "label": "Select any",
        "type": "checkbox",
        "options": [
          {
            "comment": true,
            "name": "opt517844763",
            "label": "Option 1"
          },
          {
            "comment": true,
            "name": "opt404025667",
            "label": "Option 2"
          },
          {
            "name": "opt138812904",
            "label": "Option 3"
          }
        ]
      },
      "value": [
        {
          "name": "opt517844763",
          "label": "Option 1"
        },
        {
          "name": "opt138812904",
          "label": "Option 3"
        }
      ]
    },
    {
      "field": {
        "comment": true,
        "rating": "stars",
        "name": "q194722867",
        "max": 5,
        "label": "Rate us",
        "type": "rating",
        "options": [
          {
            "comment": true,
            "name": "0",
            "label": "1"
          },
          {
            "comment": true,
            "name": "1",
            "label": "2"
          },
          {
            "comment": true,
            "name": "2",
            "label": "3"
          },
          {
            "comment": true,
            "name": "3",
            "label": "4"
          },
          {
            "comment": true,
            "name": "4",
            "label": "5"
          }
        ]
      },
      "value": [
        {
          "name": "4",
          "label": "5"
        }
      ]
    },
    {
      "field": {
        "label": "Select one (Dropdown List)",
        "type": "select",
        "options": [
          {
            "name": "opt433618125",
            "label": "Option 1"
          },
          {
            "name": "opt981936267",
            "label": "Option 2"
          }
        ],
        "name": "q134080778"
      },
      "value": [
        {
          "name": "opt981936267",
          "label": "Option 2"
        }
      ]
    }
  ]
}

Field descriptions

  • id - event ID that is unique to every new submission
  • date - submission date in UTC
  • widget - widget’s ID, type and name
  • page - URL of the page the form was filled on
  • ip - website visitor’s IP
  • location - geo-location detected by IP
    • country - full country name detected by IP
    • country_code - ISO2 country code detected by IP
    • region - full region name detected by IP
    • state_code - ISO2 state code (USA) detected by IP
    • district - name of the district/province detected by IP
    • city - full city name detected by IP
    • postal_code - postal code detected by IP
    • latitude - latitude detected by IP
    • longitude - longitude detected by IP
    • locale - locale detected by IP (e.g., en)
    • timezone - timezone detected by IP (e.g., America/New_York)
  • lang - user’s browser language, e.g., en-US
  • browser - browser name detected by user_agent
  • os - OS name detected by user_agent
  • platform - Mobile, Tablet, Desktop, Other, detected by user_agent
  • user_agent - user agent string
  • context - user’s session information
    • utm_campaign - utm_campaign parameter visitor arrived to the site with
    • utm_source - utm_source parameter visitor arrived to the site with
    • utm_medium - utm_medium parameter visitor arrived to the site with
    • utm_content - utm_content parameter visitor arrived to the site with
    • utm_term - utm_term parameter visitor arrived to the site with
    • returning - returned or first-time visitor
    • source - referrer URL, the page visitor has come from
  • custom - dictionaty of custom JS API fields
  • response - array of submitted form fields

Submitted form field descriptions

  • field - metadata dictionary
    • type - field type (email, text, textarea, radio, checkbox, select, rating)
    • name - field identifier
    • label - field name
    • comment - comments enabled/disabled attribute
    • options - list of valid options for radio, checkbox, select, rating
      • name - option identifier
      • label - option name
      • comment - comments enabled/disabled attribute
  • value - submitted data
    • email, text, textarea type fields - text
    • radio, checkbox, select, rating type fields - array of selected options
      • name - selected option identifier
      • label - selected option name
      • comment - submitted comment