Webhook Integration

Webhooks are events that trigger an action. In most cases, they are used for communication between systems. This is the simplest way of getting an alert when something happens in another system.

How to add

  • You can create a webhook by clicking create new webhook under platform webhooks.

  • You will need 2 things here.

  • The content you want to use the webhook first.

  • The second is the endpoint of the webhook.

Webhook Endpoint

  https://yourapp.com/webhook-endpoint

Webhook Settings

  • Name
    Account Wide
    Description

    With this option, this webhook will automatically work on all content in your account.

  • Name
    Use Oauth
    Description

    If your webhook endpoint requires a standard OAuth2 Bearer authorization, you can select this field to enable oauth flow for your webhook.

  • Name
    Oauth Login Endpoint
    Description

    The token request endpoint for your oauth flow.

  • Name
    Request Header
    Description

    If you want to customize the oauth token request header, you can add any number of headers.

  • Name
    Request Body
    Description

    If you want to customize the oauth token request body, you can add any number of fields.

  • Name
    Delay
    Description

    Delay in seconds between event trigger (set finish) and webhook fire in seconds. This will be usefull if you have leads on the result page and you want to give your visitors some time to get the lead data with your webhook.

  • Name
    Send Answers
    Description

    Send all the votes with the data.

  • Name
    Send Leads
    Description

    Send all user input leads with the data.

  • Name
    Send Incomplete
    Description

    Triggers webhook even if user did not see the end result.

  • Name
    Incomplete Delay
    Description

    Delay in seconds between set start and webhook fire. For example if you set this field as 120, Poltio will send votes up till 120 seconds after your visitor starts the set. If that visitor will complete the set after 120 seconds, you will also recieve another webhook event for that.

Example webhook payload

Properties

  • Name
    poltio_user_id
    Type
    integer
    Description

    Unique Poltio voter identifier. Stays unique for the same user/browser combination unless user clears cookies or uses cookiless session.

  • Name
    session_id
    Type
    string (UUIDv4)
    Description

    Unique session identifier per voter per session. Used to identify votes from a single user in a single session.

  • Name
    session_start_date
    Type
    string
    Description

    Start date-time of session. Indicates the point voter clicks start or votes for the first question in contents that skip cover screen.

  • Name
    session_end_date
    Type
    string
    Description

    End date-time of session. Indicates the point voter sees the first result.

  • Name
    publisher_uuid
    Type
    string
    Description

    Publisher Unique Identifier. This field will contain the puid or uuid query string parameter that you load the content with.

  • Name
    custom_id
    Type
    string
    Description

    Publisher Custom Identifier. This field will contain the custom_id query string parameter that you load the content with.

  • Name
    event_time
    Type
    integer
    Description

    Unix time stamp marks the prepration date for the webhook data.

  • Name
    content_type
    Type
    string
    Description

    The type of your content. Can be one of the following: set, quiz, test, survey, content

  • Name
    content_id
    Type
    string (UUIDv4)
    Description

    Unique public facing ID for the content that webhook is triggered from.

  • Name
    complete_session
    Type
    boolean
    Description

    Whether the session is completed or not.

    • Answers

  • Name
    answers
    Type
    array
    Description

    Voted answers in the content.

  • Name
    answers.question_id
    Type
    integer
    Description

    Unique Question ID for the question.

  • Name
    answers.question
    Type
    string
    Description

    Question title of answered question.

  • Name
    answers.answers
    Type
    array
    Description

    Voted (selected) answers in the question

  • Name
    answers.answers.answer_id
    Type
    integer
    Description

    Unique identifier for the answer voted by the voter.

  • Name
    answers.answer.answer
    Type
    string
    Description

    Answer title

  • Name
    answers.answers.parent
    Type
    string
    Description

    The url of the content while voting the content.

    • Result

  • Name
    result
    Type
    object
    Description

    The first result the user sees.

  • Name
    result.result_id
    Type
    integer
    Description

    Unique identifier for the result.

  • Name
    result.result_title
    Type
    string
    Description

    The title of result.

  • Name
    result.result_image
    Type
    string
    Description

    The image url of result.

  • Name
    result.result_desc
    Type
    string
    Description

    The description of result.

  • Name
    result.time_spent
    Type
    integer
    Description

    The time between the start and end of the session (ms)

  • Name
    result.right_answer
    Type
    integer
    Description

    If your content type is quiz, the number of correct answers the user answers.

  • Name
    result.calculator_result
    Type
    string
    Description

    If your content is a calculator set, the score obtained by the user.

    • Leads

  • Name
    leads
    Type
    array
    Description

    If the content for the webhook contains any lead forms, filled out information will be here.

  • Name
    leads.user_id
    Type
    integer
    Description

    Unique voter identifier.

  • Name
    leads.phone
    Type
    string
    Description

    The response to your lead's phone input

  • Name
    leads.email
    Type
    string
    Description

    The response to your lead's email input

  • Name
    leads.name
    Type
    string
    Description

    The response to your lead's name input

  • Name
    leads.comment
    Type
    string
    Description

    The response to your lead's comment input

  • Name
    leads.created_at
    Type
    string
    Description

    Lead Create Date.

  • Name
    leads.tc_checked
    Type
    boolean
    Description

    Whether the user accepts the terms and conditions

  • Name
    leads.content_type
    Type
    string
    Description

    The type of your content. (content)

  • Name
    leads.content_id
    Type
    integer
    Description

    Your content ID.

Request

POST
yourapp.com/webhook-endpoint
 {
  "poltio_user_id": 1234,
  "session_id": "22ffdf18-1035-4e56-baa2-8327e3af5242",
  "session_start_date": "2024-01-23T11:59:33.000000Z",
  "session_end_date": "2024-01-23T11:59:59.000000Z",
  "publisher_uuid": "Example Publisher ID ",
  "custom_id": "Example Custom ID",
  "event_time": 1568624875,
  "content_type": "content",
  "content_id": "6caaa000-2bd8-4b28-8b9b-bfe1fca94f39",
  "complete_session": true,
  "answers": [
      {
         "question_id": 1234,
         "question": "Example Question Title",
         "answers": [
             {
                "answer_id": 1234,
                "answer": "Example Answer Title"
                "parent": "https://www.poltio.com/widget/22ffdf18-1035-4e56-baa2-8327e3af5242"
              }
          ]
       }
    ],
  "result": {
    "result_id": 1234,
    "result_title": "Result Title",
    "result_image": "content/gcp/1678957893.2458.png",
    "result_desc": "Result Description",
    "time_spent": 16789,
    "right_answer": 0,
    "calculator_result": "0",
    },
  "leads": [
      {
         "user_id": 1234,
         "phone": "+1231231234",
         "email": "example@example.com",
         "name": "Name",
         "comment": "Comment",
         "created_at": "Lead Create Date (ISO format date (2024-01-23T11:59:43.000000Z))",
         "tc_checked": true,
         "content_type": "Content type",
         "content_id": 12345
      }
     ]
  }

Note

If you want to use result_image, you need to add Poltio CDN Path + width x height at the beginning.( You can use width and height 0 for original size. ) Example: https://cdn.poltio.com/100x100/content/gcp/1693828810.3228.jpeg)