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

Header nameDescription
x-request-idRandom request ID provided by viafoura on each HTTP request, the value is the same as “request_uuid” in the request body
authorizationAt least 64 bytes, hexadecimal. Please provide this to your CS representative
content-typeapplication/json; charset=utf-8
acceptapplication/json

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

FieldTypeDescription
request_uuidnumberSame as “X-Request-ID” in header
timenumberThe time in milliseconds
versionnumberThe current value is 1
eventsarrayArray of Event object

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.

Error CodeDescription
404Not Found
500Any internal error
400Data is not valid
200-201Request accepted
403Authorization failed

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

FieldTypeDescription
request_uuidstringrequest_id of corresponding request
resultsarrayArray of Result objects

Result object

FieldTypeDescription
event_uuidstringEvent ID
typestringEither “success” or “failure”
error_typestringArbitrary value
error_descriptionstringArbitrary value

JSON Object Definitions

Event
The event objects will describe all information related to any state change in the Viafoura system. Depending on the message_type and action additional set of fields will be included for each event.

Event triggers

Message TypeActionTrigger
livecomment_postcreatednew comment created
livecomment_postvisiblecomment enabled after moderation
livecomment_postdisabledcomment disabled by moderation or if the report (flag) threshold has been reached
livecomment_postupdatedcomment modified
livecomment_postlikedcomment liked by a user
livecomment_postunlikedcomment like reverted by a user
livecomment_postdislikedcomment disliked by a user
livecomment_postundislikedcomment dislike reverted by a user
livecomment_postflaggedcomment has been reported
livecomment_postspammedcomment was marked as spam by moderation
livecomment_postpinnedcomment was pinned to the top
livecomment_postunpinnedcomment was unpinned from the top
livecomment_postpickedcomment was marked as "editor's pick"
livecomment_postunpickedremoved the "editor's pick" mark from the comment
reply_to_livecomment_postcreatednew comment reply created
reply_to_livecomment_postvisiblecomment reply enabled after moderation
chat_messagecreatedchat message is created
chat_messagevisiblechat message is enabled after moderation
chat_messagelikedchat message liked by a user
chat_messageunlikedchat message like reverted by a user
chat_messagedislikedchat message disliked by a user
chat_messageundislikedchat message dislike reverted by a user
reply_to_chat_messagecreatedchat message reply is created
reply_to_chat_messagevisiblechat message reply is enabled after moderation
liveblog_postcreatedliveblog post is created
liveblog_postdisabledliveblog post disabled by admin
liveblog_postupdatedliveblog post modified
liveblog_postlikedliveblog post liked by a user
liveblog_postunlikedliveblog post like reverted by a user
liveblog_postdislikedliveblog post disliked by a user
liveblog_postundislikedliveblog post dislike reverted by a user
liveblog_postpickedliveblog post was marked as "editor's pick"
liveblog_postunpickedremoved the "editor's pick" mark from the liveblog post
liveblog_postpinnedliveblog post was pinned to the top
liveblog_postunpinnedliveblog post was unpinned from the top

Event fields

FieldTypeDescription
event_uuidstringEvent ID
timenumberThe time in millisecond
message_typestringlivecomment_post
reply_to_livecomment_post
liveblog_post
chat_message
reply_to_chat_message
actioncreated
visible
disabled
updated
liked
unliked
disliked
undisliked
flagged
spammed
pinned
unpinned
picked
unpicked
content_uuidstringid of the content item that was interacted on
actor_uuidstringid of the user or actor who caused the interaction (this could be internal ids in the case of moderation events)
author_uuidstringid of the user who created the content (e.g. the author of the comment)
content_container_uuidstringid of the content container that was interacted on
section_uuidstringid of the viafoura section where the action occurred
page_urlstringa full URL which the action occurred

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' 
    } 
  ] 
}

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 [API 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.