We now provide customers with near real-time access to all notifications generated by the Viafoura conversations widget and broadcast api events, allowing integration into your own communication channels when leveraging these two tools.

With our Notifications Webhook, you can send notifications using your existing tools, templates and user preferences, allow for new formats such as digest notifications or integration into existing newsletters, integrate Viafoura notifications and preferences into your on-site user profiles, and manage notifications as part of your overall push strategy to tune cadences & opt-ins.

Notification events differ from the current Webhook user-content-action events. While user-content-action events encompass all user actions on the platform, notification events are a curated subset targeted at specific recipients, plus broadcast capability, to enhance user engagement.

Notification events include:

Event	Description
broadcast_site	Broadcasts a message to all users of a site.
broadcast_topic	Broadcasts a message to all subscribers of a topic.
follow	When a user follows another user.
like	When a user likes another user's content.
reply	When a user replies to a user's content.
reply_removed	When a user's reply is removed (in order to properly update Notification Feeds).
subscribed_page_content	Notifies followers of a container of new posts or replies on that container.
subscribed_user_content	Notifies followers of a user that the user posted new content.

Access to the webhooks feature will need to be activated by your customer success representative.

Flow Diagram

Webhook Call

The service will post the notification webhook requests to the customer-provided notification webhook endpoint. Please reach out to your Viafoura support representative to configure your endpoint in the Admin console for your preferred domains.

Notification endpoint

The notification endpoint should be an HTTPS endpoint that can receive the following type of request:

Request Protocol and Method: HTTPS POST

Request Headers & Authorization

Header name	Value
x-request-id	Random request ID provided by Viafoura on each HTTP request, the value is the same as “request_uuid” in the request body
authorization	The customer-provided authorization token, for authenticating the requests
content-type	application/json; charset=utf-8
accept	application/json

Request Body

A JSON formatted body:

{
  "request_uuid": "4d3cdfe6-25d6-42cd-a1f0-1003b299fc7a",
  "time": 1714243693158,
  "version": 1,
  "notifications": [Notification...]
}

Notification object:

{
  "notification_type": ("broadcast_site"|"broadcast_topic"|"like"|"reply"|"subscribed_page_content"|"subscribed_user_content"|"follow"|"reply_removed")
  "notification_uuid": "dd6124eb-5f03-4d49-8acc-a80effe35dc3",
  "time": 1714244587448,
  "section_uuid": "00000000-0000-4000-8000-010fdf3f0a45",
// if specific to a container:
  "content_container_uuid": "0dc371b9-cecd-4dc3-954b-e5255794e2e7",
  "user": User,
  "recipients": [User...]
  "payload": {
    "url": "https://yoursite.com/article-title-or-content-url",
    "image_url": "https://images.yoursite.com/article-thumbnail.jpg"
// if Broadcast:
    "title": "Title of Broadcast",
    "description": "Description of broadcast",
// if Broadcast Topic:
    "topic_id": "topic_of_broadcast",
// if is a post/reply/like, the relevant Content:
    "content": {
      "uuid": "ad6124eb-5f03-4d49-8acc-a80effe35dc3",
      "body": "Hello there"
    }
// if targets other content:
    "target_content_uuid": "e185ffbc-c5c1-4811-aeef-7cd4f700284e",
  }
}

User Object:

{
  "name": "First Last",
  "viafoura_id": {
    "uuid": "3d4e5c0d-584f-4b89-a2c1-bfd8d9f3d546",
    "id": "1234567890"  
  },
  "external_id": {
    "provider": "google",
    "id": "f00b4r"
  }
}

How `url` and `image_url` are populated

For reply and like notifications, payload.url is the address of the page the comment was posted on, followed by #vf-<content uuid> so the link opens at that comment. The page address is read from the page's vf:url meta tag, then og:url. If neither tag is present, the browser's address at the time of posting is used, including any # fragment.

payload.image_url is read from the page's vf:image meta tag, then og:image. It may be an empty string ("") when the page has no image tag.

Both values are captured when the comment is posted. Changing the page's tags later does not change them for comments that already exist.

See Content Association for the full list of supported meta tags.

Page requirements for reply and like notifications

⚠️
To make sure reply and like notifications reach your endpoint, every page that hosts a conversation should have:

an og:url (or vf:url) meta tag containing the canonical page URL, without a # fragment, and

either an og:image (or vf:image) meta tag with a valid absolute image URL, or no image tag at all. Do not include an image tag without a content value.

If a comment is posted from a page without a canonical URL tag while the browser address contains a # (for example after clicking a href="#" link, or when opening a shared comment link), or from a page with an empty image tag, the notification still appears in the reader's on-site notification tray. It is not sent to your webhook endpoint, and it is not retried.
Adding the tags fixes notifications for comments posted afterwards. Notifications about comments that were posted before the fix (for example, a new like on an older comment) may still not be delivered.

Expected Response

Success: 204 No Content

Failure that should be retried: Any 500 error

Failure that should NOT be retried: Any 400 error

Timeout

Requests will timeout if the response time exceeds our timeout threshold (5 seconds as of this writing), and be considered a 500 error.

Retries

Retryable failures will be retried up to a maximum number of times (5 as of this writing). If all retries are exhausted, the notification will be discarded.

Retries will follow an exponential back-off strategy.

Notifications that cannot be built because of missing page information (see Page requirements for reply and like notifications) are never sent, so they are neither counted as failures nor retried.

Examples

Site Broadcast

{
  "request_uuid": "11111111-1111-1111-1111-111111111111",
  "time": 1714241702104,
  "version": 1,
  "notifications": [
    {
      "notification_type": "broadcast_site",
      "notification_uuid": "33333333-3333-4333-8333-333333333333",
      "time": 1714241702092,
      "section_uuid": "22222222-2222-4222-8222-222222222222",
      "recipients": [],
      "payload": {
        "url": "https://www.example.com",
        "image_url": "https://cdn.example.com/image.jpg",
        "title": "Title",
        "description": "Description content here."
      }
    }
  ]
}

Topic Broadcast

{
  "request_uuid": "706a751e-424b-475c-83f0-99493197bff0",
  "time": 1720629497078,
  "version": 1,
  "notifications": [
    {
      "notification_type": "broadcast_topic",
      "notification_uuid": "e4feacd7-c472-4cda-bba1-957ef9b55a2b",
      "time": 1720629496748,
      "section_uuid": "00000000-0000-4000-8000-000000000bc8",
      "recipients": [
        {
          "name": "Alice",
          "viafoura_id": {
            "uuid": "00000000-0000-4000-8000-07034392f200",
            "id": 7710600000000
          },
          "external_id": {
            "provider": "google",
            "id": "abc"
          }
        },
        {
          "name": "Bob",
          "viafoura_id": {
            "uuid": "00000000-0000-4000-8000-081872e75300",
            "id": 8901100000000
          },
          "external_id": {
            "provider": "facebook",
            "id": "def"
          }
        }
      ],
      "payload": {
        "url": "https://www.example.com",
        "image_url": "https://cdn.example.com/image.jpg",
        "title": "The title",
        "description": "The description",
        "topic_id": "sports"
      }
    }
  ]
}

User Notification

{
  "request_uuid": "7036d35c-02b3-4cf6-9395-081dda4d619f",
  "time": 1720123316470,
  "version": 1,
  "notifications": [
    {
      "notification_type": "like",
      "notification_uuid": "f1576f8f-17bd-4353-801c-df14793b693a",
      "time": 1720123316045,
      "section_uuid": "00000000-0000-4000-8000-000000000bc5",
      "content_container_uuid": "5b64a008-51c6-4620-b458-66a828276b4e",
      "user": {
        "name": "Bob",
        "viafoura_id": {
          "uuid": "00000000-0000-4000-8000-075d8e415800",
          "id": 8098400000000
        },
        "external_id": {
          "provider": "facebook",
          "id": "def"
        }
      },
      "recipients": [
        {
          "name": "Claire",
          "viafoura_id": {
            "uuid": "00000000-0000-4000-8000-031ae837bd00",
            "id": 3414100000000
          },
          "external_id": {
            "provider": "linkedin",
            "id": "ghi"
          }
        }
      ],
      "payload": {
        "url": "https://www.example.com#vf-b9b6d109-630e-4305-8939-b65aaf3da85e",
        "image_url": "https://cdn.example.com/image.jpg",
        "content": {
          "uuid": "b9b6d109-630e-4305-8939-b65aaf3da85e",
          "body": "Body of the liked post"
        },
        "target_content_uuid": "b9b6d109-630e-4305-8939-b65aaf3da85e"
      }
    }
  ]
}

Example code for a notifications webhook service using Viafoura's Notification Webhook:

https://github.com/viafoura/Viafoura-Examples