Webhooks

Viafoura supports third-party services to receive audience engagement events in near real-time. Business intelligence and reporting dashboards can be enriched and empower your staff with insights into the real-time activity of your audience as they engage with content and each other.

You will need to:

1. Configure an endpoint and provide the API path
2. Provide us with an Authentication header we can pass to your API to let you know it's coming from us

Please contact your client success representative with this information and they will get this set up with you.

Webhooks Details

Security
Note that:
The service will be available over SSL (https) using a valid certificate
Viafoura application will use the certificate for both Authentication and Authorization

Conversation Pattern
The conversation between client and server will be Fire and Forget.
RESTful Service Specification

Request
Scheme: https
URL: will be provided by you to your CS representative
*HTTP Method: POST

Parameters

Request Headers

Request Body
The request body is a JSON encoded string that follows the schema below:

Response
HTTP Status
A 200, 201 or 202 response code is expected in the HTTP response code. However third-party service can return other status codes to let our customer success team help with diagnosing possible issues in the integration.

Response Body from Third Party Service
The expected response from the third party service will only be parsed if the following schema is used.

Result object

JSON Object Definitions

Event
Event objects describe state changes in the Viafoura system. Additional fields may be included based on message_type and action.

Poll-vote events are delivered through the User Action callback (USER_ACTION_SERVER_CALLBACK_ENDPOINT) using the same /content-actions request shape as other content-action events.

Event triggers

Event fields

Poll vote event fields

detail is present only when message_type is poll_vote. It contains a snapshot of the poll when the vote was cast; later changes to the question or options do not change an event that has already been delivered.

For poll_vote events, actor_uuid identifies the voter. author_uuid, topic_id, topic_name, and page_url are absent. Fields with null values are omitted from the request body.

When poll votes are not delivered

Viafoura does not send a poll_vote event when:

• A signed-out visitor casts the vote. Poll-vote events require actor_uuid.
• The upstream record has no payload or poll UUID.
• The source topic message is not a vote.

Example

Request

{ 
 request_uuid: 'abcc2254-b0a4-492c-a8f2-ae7820f4968a',
 time: 1593205167183,
 version: 1,
 events:
  [ 
    { event_uuid: '99d2a532-e1a1-4455-834a-775148570e9d',
      time: 1593205166938,
      section_uuid: '00000000-0000-4000-8000-337a437adec1',
      content_container_uuid: '0dc371b9-cecd-4dc3-954b-e5255794e2e7',
      content_uuid: 'bf890170-4828-4d1d-a1b0-a0072a6117d3',
      actor_uuid: '00000000-0000-4000-8000-017ea245f200',
      author_uuid: '00000000-0000-4000-8000-485fe358a524',
      message_type: 'livecomment_post',
      page_url: 'https://action.click/livecomments/actioncomments.html',
      action: 'liked' 
    } 
  ] 
}

Poll vote request

{
  "request_uuid": "3f578154-5e7b-470e-8f40-038f5c40d08c",
  "time": 1788381240669,
  "version": 1,
  "events": [
    {
      "event_uuid": "01a063d4-1d55-714c-8bdf-36f732b99465",
      "section_uuid": "00000000-0000-4000-8000-000000000bda",
      "content_container_uuid": "01a063d0-37d6-7b71-bf52-af42d0c01016",
      "content_uuid": "9f1c2f7e-0000-4000-8000-000000000001",
      "actor_uuid": "00000000-0000-4000-8000-0000000013b1",
      "message_type": "poll_vote",
      "action": "voted",
      "detail": {
        "poll_uuid": "9f1c2f7e-0000-4000-8000-000000000001",
        "poll_question": "Which option do you prefer?",
        "options": [
          {
            "option_uuid": "aaaa0000-0000-4000-8000-000000000001",
            "option_description": "Option A",
            "is_selected": true
          },
          {
            "option_uuid": "bbbb0000-0000-4000-8000-000000000002",
            "option_description": "Option B",
            "is_selected": false
          }
        ]
      }
    }
  ]
}

Follow author request

{
  request_uuid: 'abcc2254-b0a4-492c-a8f2-ae7820f4968a',
  time: 1593205167183,
  version: 1,
  events: [
    {
      event_uuid,
      time,
      section_uuid,
      actor_uuid,
      author_uuid,
      message_type: 'follow_author',
      action: 'followed'
    }
  ]
}

Follow topic request

{
  request_uuid: 'abcc2254-b0a4-492c-a8f2-ae7820f4968a',
  time: 1593205167183,
  version: 1,
  events: [
    {
      event_uuid,
      time,
      section_uuid,
      actor_uuid,
      message_type: 'follow_topic',
      action: 'followed',
      topic_id: 'sports/nba',
      topic_name: 'NBA'
    }
  ]
}

The unfollowed variants are identical except action: 'unfollowed'.

Response

{
    "request_uuid": "c71b5cb1-ce44-4239-8b6e-87b99cf2b1f0",
    "results": [
        {
            "event_uuid":"c71b5cb1-ce44-4239-8b6e-87b99cf2b1a0",
            "type": "failure",
            "error_type": "unknown",
            "error_description": "unable to store"
        },
        {
            "event_uuid":"dd519c8a-3619-4cb0-b31b-0ffd14d24aab",
            "type": "success"
        },
        {
            "event_uuid":"d8a6a231-0cef-4385-83d8-66b6160811a5",
            "type": "success"
        },
        {
            "event_uuid":"5c0c5ab3-f3be-4194-bfc5-2000f94665ad",
            "type": "success"
        }
    ]
}

Integration Testing

1. Sign up for RequestBin which is a free Webhook testing platform.
2. Pipedream will provide a public callback URL which you need to configure in Viafoura Admin → General → Notifications for the site you want to test as shown below.
3. You will also need to get your API key from your pipe dream account by going to your Pipedream Account Settings page.
4. In Viafoura Admin → General → Notifications under the server-to-server callback authorization header parameter, configure the Pipedream API Key as ‘Bearer PI Key]’ ’ as shown below.
5. Contact your Viafoura Customer Success Manager to enable Server-to-Server callbacks for your domain.

Done! Now when you perform actions that trigger webhook messages on the site you configured you will see the Webhook messages in Pipdream under the page for the Requestbin you created.