Notifications Webhook
Provides support for a customer's system to receive user-notification events in near real-time.
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
![](https://files.readme.io/bf87a3f-Screenshot_2024-07-11_at_9.23.36_AM.png)
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:
Updated about 2 months ago