We now provide customers with near real-time access to all notifications generated by Viafoura, allowing integration into your own communication channels.

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

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.

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