Polly Webhooks

Polly’s webhook creator allows you to easily send the results of your pollys to a 3rd party location.

Webhook FAQs

Who can use Polly webhooks? 

If you have access to the Polly API, you also have access to webhooks! (It's a total win win situation 😉) More on setting up Polly API can be found here

What is a webhook?

Simply put, a webhook (also known as a web callback or reverse API) is an efficient and easy way to get real-time data delivered to another application.

When set up, a webhook delivers data (typically JSON or XML) to other applications as it happens. Once a webhook is configured and created, each time a specific event occurs it will send data to a specific URL via a HTTP POST request.

How is a webhook different from an API?

Simply put, an API will do something when you ask it to do something and a webhook will do it automatically based on an event. For example, if you wanted to pull information on new users using the API, you would have to periodically send a HTTP GET request to /users, store those users somewhere, and check the difference between the previous list of users and the newly gotten list of users.

💡Instead, you could create a webhook that listens for an event called new_user_created and the webhook would deliver data around that new user to a URL that you specify.

How does a webhook work with Polly?

Polly provides a simple UI to work with webhooks in the Polly application. As a user on the web application, you'll be able to interact with webhooks in the following ways: 

• View a list of your webhooks
• Create a new webhook
• Edit an existing webhook
• Enable or Disable an existing webhook
• Delete an existing webhook

As an added bonus, you'll be able to create new webhooks with a few pre-populated fields (Description, Filter By, and Object ID) via shortcuts located on the Poll / Survey / Workflow pages.

How to Create a Webhook

You can access the webhook creator a couple different ways within the Polly web app:

1. Toggle to the API tab on the left hand navigation > Click Webhooks > then click the Create Webhook button:

2. Use one of the included shortcuts by going to the results of the poll/survey/workflow for which you’d like to set up a webhook, click the ⚙️Controls button in the top right corner, then click Create Webhook:

Once you’re in the webhook creator, you’ll need to fill out the following fields:

1. Description: Description of the purpose of the webhook to help you easily tell it apart from any others you create. E.g. 'Webhook for Phil's Lunch Survey'
2. URL: The URL where you want the webhook to deliver the HTTPS POST JSON payload to. It must be a valid HTTPS url.
3. Data Access: By default, data access will be set to User which means that the webhook you're creating will only receive events related to your user's polls and surveys. If you are an Organization Administrator you have the option to set data access to Workspace, which means that this webhook will receive events related to all users' polls and surveys within your Organization.
4. Events to Subscribe to: You must pick at least one but can have multiple events to subscribe to. There are events for both polls and surveys.
   
   If you’re setting up a webhook for a polly, the events are:
   
   • response_created - For a given poll, when the user selects an option the webhook will deliver a JSON payload to the URL specified.
   • response_changed - For a given poll, each time the user changes their option the webhook will deliver a JSON payload to the URL specified.
   • response_deleted - For a given poll, each time the user removes their response the webhook will deliver a JSON payload to the URL specified.

   If you’re setting up a webhook for a multi-question polly the events are:

   • Survey_submitted - For a given survey, each time the user completes a survey the webhook will deliver a JSON payload to the URL specified.
   • Survey_updated -For a given poll, each time the user changes their answers to the survey the webhook will deliver a JSON payload to the URL specified

   ✏️Note: If you’re setting up a webhook for a workflow that contains both polls and surveys, you need to choose at least one poll event and one survey event.

   
   We also have an event for workflows called workflow.triggered, this can be used for tracking data around your workflow processes. If you're interested in using this, reach out to your CSM for more info.

5. Filter By: You can filter your webhook to only listen for a specific poll, survey, recurring poll/survey or workflow by using the Filter By dropdown. If you use Filter By you'll be given a Object Id text input where you must enter the ID of the corresponding poll, survey, recurring survey/poll, or workflow you want to filter by.

   To find your object ID, simply click into the results of the poll/survey/workflow you're setting up the webhook for.

   In the URL, you'll see a string of letters and numbers which is your object ID.

   You can select 'No Filter' which will enable the webhook to send information for every survey/poll/workflow that belongs to you for the specified events you selected.

6. Verification Secret: You can specify your own Verification secret or we can generate one for you, either way the decision is up to you! We use the Verification secret with the Verification method.

7. Verification Method: You have two options. Verify with Signature (recommended) or Verify with Secret. 

• If you pick 'Verify with Signature', we'll sign each request with the Verification secret and include the signature in the X-HOOK-SIGNATURE header. 
• If you pick 'Verify with Secret' we'll include the secret in the X-HOOK-SECRET header.

Here’s a screenshot of a completed webhook form:

Finishing Up

Once you’ve filled out all of the fields required, you can hit create webhook, and it will show up under the webhooks tab. From this view, you can choose to disable/enable, edit, or delete your webhook.