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
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

Event fields

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.