Notification Webhook

Have event information sent to a webhook endpoint

The Notification Webhook enables you to monitor message-related events. Through a POST API call, the Notification Webhook sends event information to a webhook endpoint, such as those in the following list:

  • Someone liked your message
  • Your message was approved or rejected
  • Someone replied to your message
  • An author you follow posted a new article
  • A new topic that has a keyword you follow has been posted
  • Someone mentioned you in a comment

The following sections explain how to set up and maintain the Notification Webhook.



Set up the Notification Webhook

  1. Review the implementation best practices.
  2. Create a webhook endpoint.
  3. Identify the notification events that you want to receive.
  4. Contact your OpenWeb representative with your webhook endpoint and the list of notifications. Your OpenWeb representative will create and configure a unique authenticated endpoint request for you.


Best Practices

The following sections explain the best practices pertaining to your webhook endpoint, event processing, delivery attempts and retries, and security. Adhering to this guidance helps to ensure that your webhook notifications are properly received and handled.


Webhook Endpoint

The following items ensure that events delivered to your webhook endpoint are handled correctly:

  • Webhook endpoints must accept HTTPS connections.
  • Webhook endpoints must accept POST HTTP requests.

Event Processing

  • Event processing should account for receiving the same event more than once. We advise you to guard against duplicated events by checking the event id or making your event processing idempotent.
  • Event processing should rely upon event timestamps. Events are not guaranteed to be delivered in chronological order.

Delivery attempts and retries

If OpenWeb does not receive a 2xx response within 10 seconds of posting an event to your webhook endpoint, an attempt to resend the event occurs every 40 minutes. After 24 hours, OpenWeb stops trying to resend the event.

If your endpoint has been disabled or deleted when a retry is attempted, future retries of that event will be prevented. However, if you disable and then re-enable a webhook endpoint before a retry attempt, you should still expect to receive future retry attempts.


Security

When OpenWeb sends an event notification to a registered webhook, an x-openweb-notification-event-webhook-token header is included so that you know the request was sent from OpenWeb servers.

OpenWeb strongly recommends that you verify the header when you receive a request at your webhook endpoint.



Events

Event types

OpenWeb enables you to configure your webhook endpoints to receive only the types of events required by your integration. The following table lists all supported event types.

Notification EventDescription
liked-messageSomeone liked your message
moderation-decisionYour message was approved or rejected
replied-your-messageSomeone replied to your message
topic-by-authorThere is a new article from an author you are following
topic-by-keywordThere is a new topic by keyword you are following
user-mentionedSomeone mentioned you in a comment

Response

Each type of event returns a specific event response...

{
   "event_id": 6738563953184685040, // event hash
   "channels": [
       "email",
       "in-app"
   ],
   "type": "liked-message",
   "action_link": "http://some.url",
   "conversation_id": "sp_123abc_post1",
   "conversation_title": "Article Title",
   "user": { // recipient
       "id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "comment": {
       "content": [{
               "type": "text|image|animation",
               "text": "message for you",
               "url": "https://fullpath/image"
       }],
       "type": "comment",
       "comment_id": "sp_123abc_post1_c_123",
       "timestamp": 1641492345
   },
   "total_count": 10,
   "liker": {
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "OrangeToast",
       "registered": false
   },
   // optional
   "custom_data": "{\"sp_123abc_post1_c_123\":{\"app_bundle_id\":\"im.spot.demo.123\"}}"
{
   "event_id": 6738563953184685040, // event hash
   "channels": [
       "email",
       "in-app"
   ],
   "type": "message-approved", // could also be message-rejected
   "action_link": "some.url",
   "conversation_id": "sp_123abc_post1",
   "conversation_title": "Article Title",
   "user": { // recipient
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "comment": {
       "content": [{
               "type": "text|image|animation",
               "text": "message for you",
               "url": "https://fullpath/image"
       }],
       "comment_id": "sp_123abc_post1_c_123",
       "state": "approved",
       "type": "comment",
       "timestamp": 1642598712
   },
   // optional
   "custom_data": "{\"sp_123abc_post1_c_123\":{\"app_bundle_id\":\"im.spot.demo.123\"}}"
{
   "event_id": 6738563953184685040, // event hash
   "channels": [
       "email",
       "in-app"
   ],
   "type": "replied-your-message",
   "action_link": "https://some.url",
   "conversation_id": "sp_123abc_post1",
   "conversation_title": "Article Title",
   "user": { // recipient
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "comment": {
       "content": [{
               "type": "text|image|animation",
               "text": "message for you",
               "url": "https://fullpath/image"
       }],
       "comment_id": "sp_123abc_post1_c_123",
       "type": "comment",
     "timestamp": 1643201248
   },
   "replier": {
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "reply": {
       "content": [{
               "type": "text|image|animation",
               "text": "boring reply",
               "url": "https://fullpath/image"
       }],
       "comment_id": "sp_123abc_post1_c_123_r_321",
       "type": "reply",
       "timestamp": 1643201248
   },
   // optional
   "custom_data": "{\"sp_123abc_post1_c_123\":{\"app_bundle_id\":\"im.spot.demo.123\"},\"sp_123abc_post1_c_123_r_321\":{\"app_bundle_id\":\"im.spot.demo.123\"}}"
{
   "event_id": 6738563953184685040, // event hash
   "channels": [
       "email",
       "in-app"
   ],
   "type": "topic-by-author | topic-by-keyword",
   "action_link": "https://some.url",
   "conversation_id": "sp_123abc_post1",
   "conversation_title": "Article Title",
   "description": "Some description",
   "timestamp": 1642598712,
   "user": { // recipient
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "keywords": [
       "Chris Columbus"
   ],
   "authors": [
       "John Doe"
   ],
   // optional
   "custom_data": ""
}
{
   "event_id": 6738563953184685040, // event hash
   "channels": [
       "email",
       "in-app"
   ],
   "type": "user-mentioned",
   "action_link": "http://some.url",
   "conversation_id": "sp_123abc_post1",
   "conversation_title": "Article Title",
   "user": { // recipient
       "user_id": "sso_id",
       "user_name": "Guest",
       "display_name": "CyanStrawberry",
       "registered": false
   },
   "comment": {
       "content": [{
           "type": "text|image|animation",
           "text": "message for you",
           "url": "https://fullpath/image"
       }],
       "comment_id": "sp_123abc_post1_c_123",
       "type": "comment",
       "timestamp": 1641384172
   },
   "mentioner": {
       "user_id": "u_222bbb",
       "user_name": "Guest",
       "display_name": "BlueBeer",
       "registered": false
   },
   // optional
   "custom_data": "{\"sp_123abc_post1_c_123\":{\"app_bundle_id\":\"im.spot.demo.123\"}}"

Response Parameters

Parameter Description
action_link string Link to the comment
authors array List of article creators being followed
channels array Possible values:
   • email
   • in-app
comment object Contents and metadata of the comment

See: comment object
conversation_id string Unique identifier that is a combination of the Spot ID and post ID
conversation_title string Title of the article
custom_data object Partner-specific settings defined by OpenWeb
description string Informational summary of the article
event_id integer Unique identifier for the notification event
keywords array List of one or several keywords being followed
liker object Information about the user who liked a message written by the notification recipient

See: liker object
mentioner object Information about the user who mentioned the notification recipient within a comment

See: mentioner object
replier object Information about the user who replied to a comment written by the notification recipient

See: replier object
reply object Contents and metadata of the reply

See: reply object
timestamp integer Time of the notification in Unix Epoch time
total_count integer Sum of messages
type string Type of webhook notification

Possible values:
   • liked-message
   • message-approved
   • replied-your-message
   • topic-by-author
   • topic-by-keyword
   • user-mentioned
user object Information about the user receiving the notification

See: user object


comment object

Parameter Description
comment_id string Unique identifier of the comment
content object See: comment.content object
state string Approval status of a comment

Possible values:
   • approved
   • blocked
timestamp integer Time of the notification in Unix Epoch time
type string Type of comment

The value of this parameter is always comment.


comment.content object

Parameter Description
text string Written, non-image content of the comment
type string Type of content of the comment

Possible values:
   • animation
   • image
   • text
url string URL of the image in the comment


liker object

Parameter Description
display_name string Non-unique personal identifier used prominently throughout the platform

A display name has the following characteristics:
   • Cannot exceed 30 characters
   • Is comprised of a combination of letters, numbers, special characters, or spaces

When not provided, the name will be Guest.
registered boolean Identifies if the user is a registered user

   • true: User is registered
   • false: User is not registered
user_id string Unique, single sign on identifier for the user
user_name string Unique personal identifier used to differentiate between different users

A username has the following characteristics:
   • Is greater than 3 characters, but less than 30 characters
   • Can be comprised of foreign-language characters
   • Cannot be comprised of delimiters, such as spaces, tabs, and other ASCII delimiters (/t, /r, and /n)
   • Cannot be comprised of special characters, such as < and >
   • Is preceded by the @ symbol when displayed

If a username is already taken, OpenWeb appends random letters or numbers to generate a unique version of that username and registers it to the user.

If a username is not provided, OpenWeb creates a username from the display_name, appends random letters or numbers to generate a unique version of that username, and registers it to the user.


mentioner object

Parameter Description
display_name string Non-unique personal identifier used prominently throughout the platform

A display name has the following characteristics:
   • Cannot exceed 30 characters
   • Is comprised of a combination of letters, numbers, special characters, or spaces

When not provided, the name will be Guest.
registered boolean Identifies if the user is a registered user

   • true: User is registered
   • false: User is not registered
user_id string Unique, single sign on identifier for the user
user_name string Unique personal identifier used to differentiate between different users

A username has the following characteristics:
   • Is greater than 3 characters, but less than 30 characters
   • Can be comprised of foreign-language characters
   • Cannot be comprised of delimiters, such as spaces, tabs, and other ASCII delimiters (/t, /r, and /n)
   • Cannot be comprised of special characters, such as < and >
   • Is preceded by the @ symbol when displayed

If a username is already taken, OpenWeb appends random letters or numbers to generate a unique version of that username and registers it to the user.

If a username is not provided, OpenWeb creates a username from the display_name, appends random letters or numbers to generate a unique version of that username, and registers it to the user.


replier object

Parameter Description
display_name string Non-unique personal identifier used prominently throughout the platform

A display name has the following characteristics:
   • Cannot exceed 30 characters
   • Is comprised of a combination of letters, numbers, special characters, or spaces

When not provided, the name will be Guest.
registered boolean Identifies if the user is a registered user

   • true: User is registered
   • false: User is not registered
user_id string Unique, single sign on identifier for the user
user_name string Unique personal identifier used to differentiate between different users

A username has the following characteristics:
   • Is greater than 3 characters, but less than 30 characters
   • Can be comprised of foreign-language characters
   • Cannot be comprised of delimiters, such as spaces, tabs, and other ASCII delimiters (/t, /r, and /n)
   • Cannot be comprised of special characters, such as < and >
   • Is preceded by the @ symbol when displayed

If a username is already taken, OpenWeb appends random letters or numbers to generate a unique version of that username and registers it to the user.

If a username is not provided, OpenWeb creates a username from the display_name, appends random letters or numbers to generate a unique version of that username, and registers it to the user.


reply object

Parameter Description
comment_id string Unique identifier of the comment
content object See: reply.content object
timestamp integer Time of the notification in Unix Epoch time
type string Type of comment

The value of this parameter is always reply.


reply.content object

Parameter Description
text string Written, non-image content of the reply
type string Type of content of the reply

Possible values:
   • animation
   • image
   • text
url string URL of the image in the reply


user object

Parameter Description
display_name string Non-unique personal identifier used prominently throughout the platform

A display name has the following characteristics:
   • Cannot exceed 30 characters
   • Is comprised of a combination of letters, numbers, special characters, or spaces

When not provided, the name will be Guest.
id string Unique, single sign on identifier for the user
registered boolean Identifies if the user is a registered user

   • true: User is registered
   • false: User is not registered
user_id string Unique, single sign on identifier for the user
user_name string Unique personal identifier used to differentiate between different users

A username has the following characteristics:
   • Is greater than 3 characters, but less than 30 characters
   • Can be comprised of foreign-language characters
   • Cannot be comprised of delimiters, such as spaces, tabs, and other ASCII delimiters (/t, /r, and /n)
   • Cannot be comprised of special characters, such as < and >
   • Is preceded by the @ symbol when displayed

If a username is already taken, OpenWeb appends random letters or numbers to generate a unique version of that username and registers it to the user.

If a username is not provided, OpenWeb creates a username from the display_name, appends random letters or numbers to generate a unique version of that username, and registers it to the user.


Did this page help you?