Webhook events

As an API user, you can always fetch the latest notifications for a user by calling the notifications endpoint, but you can also get real time updates by adding a webhook URL.

Adding a webhook

We are working on API access to webhooks, but in the meantime, as a customer you can add your webhook through our Admin interface.

1. Add a URL that will receive webhook calls from us
2. Choose an authentication method:
   1. API key - Your API key will be sent in a X-Webhook-keyheader with the request.
   2. Customer header - You can specify the name and value of the headers that should be sent with the request.
   3. OAuth - We will use a token retrieved from the token URL and client credentials you specify.

Receiving the request

All webhook events are send as an application/json POST request to the specified URL, and the body contains the following envelope:

{"kind": $PAYLOAD_KIND, "data": $PAYLOAD, "meta": $WEBHOOK_METADATA }

Currently the only supported kind is NOTIFICATIONand its payload is the same notification object delivered by the API from the notifications endpoint. The intended recipient of the notification can be found in the profile_idfield in the metadata:

Example notification webhook body

Full notification payload schema can be found in the API documentation

{
  "kind": "NOTIFICATION", 
  "data": {
  	"id": "96146a3a-be9d-4929-9330-41c95c6ca2da",
    "kind": "OWN_PROFILE_POST",
    "sender": "5a19f948-4222-4aaf-9c36-a35d4fb2b66a",
    "title": "Bob wrote a post",
    "body": "...",
    ...
  },
  "meta": { 
    "profile_id": "9b1d4264-7031-4bbf-a929-5008826085e2"
}

Notification kind and events

The kind field describes the event that triggered or generated the given notification. Below is the list of all possible values and explanations.

FOLLOW_GROUP

This type of notification is created when some user (follower) follows the group. The recipients of this notification are the admins of the group. Example:

{
  "kind": "FOLLOW_GROUP",
  "sender": <follower_id>,
  "group": <group_id>
  ...
}

FOLLOW_PORTFOLIO

[Currently unused]

FOLLOW_PROFILE

This type of notification is created when some user (follower) follows the other user (followee). The recipient of this notification is the user who was followed (i.e. followee). Example:

{
  "kind": "FOLLOW_PROFILE",
  "sender": <follower_id>,
  "group": <group_id>
  ...
}

GROUP_INVITE

This type of notification is created when GroupInvite is created. The recipient of this notification is the user who was invited (i.e. GroupInvite.recipient). Example:

{
  "kind": "GROUP_INVITE",
  "sender": <group_admin_id>,
  "group": <group_id>
  ...
}

GROUP_INVITE_ACCEPTED

This type of notification is created when the user accepts the GroupInvite. The recipient of this notification is the admin of the group who initially sent the invite. (i.e. GroupInvite.sender). Example:

{
  "kind": "GROUP_INVITE_ACCEPTED",
  "sender": <invited_user_id>,
  "group": <group_id>
  ...
}

GROUP_POST

This type of notification is created when a new post in the group is created. The recipients of this notification are the followers of the group (except the ones who muted the group). Example:

{
  "kind": "GROUP_POST",
  "sender": <post_author_id>,
  "post": <created_post_id>
  ...
}

GROUP_REQUEST

This type of notification is created when GroupRequest is created. The recipient of this notification is the admins of the group. Example:

{
  "kind": "GROUP_REQUEST",
  "sender": <group_request_sender_id>,
  "group": <group_id>
  ...
}

GROUP_REQUEST_ACCEPTED

This type of notification is created when admins accept the GroupRequest. The recipient of this notification is the user who initially sent the request. (i.e. GroupRequest.sender). Example:

{
  "kind": "GROUP_REQUEST_ACCEPTED",
  "sender": <group_admin_id>,
  "group": <group_id>
  ...
}

INSTRUMENT_POST

This type of notification is created when a new post under the instrument (i.e. post["kind"] = "INSTRUMENT") is created. The recipients of this notification are the followers of the given instrument. Example:

{
  "kind": "INSTRUMENT_POST",
  "sender": <post_author_id>,
  "post": <created_post_id>
  ...
}

MENTION_INSTRUMENT

[Currently unused]

MENTION_PROFILE

This type of notification is created when a user (post author) creates a post and tags / mentions the other user (tagged user). The recipient of this notification is the tagged user. Example:

{
  "kind": "MENTION_PROFILE",
  "sender": <post_author_id>,
  "post": <created_post_id>
  ...
}

NEW_MESSAGE

This type of notification is created when a user (sender) sends a message to the user. The recipient of this notification is the receiving user. Example:

{
  "kind": "NEW_MESSAGE",
  "sender": <sender_id>,
  "message": <message>
  ...
}

OWN_PROFILE_POST

This type of notification is created when a user (author) creates a post on their own profile wall. The recipients of this notification are the followers of the author. Example:

{
  "kind": "OWN_PROFILE_POST",
  "sender": <author_id>,
  "post": <created_post_id>
  ...
}

OWN_TRANSACTION

This type of notification is created several days after the transaction (and subsequently a transaction post is created). In other words, it is a reminder to comment on the transaction post generated by the transaction. The recipient of this notification is the user itself. The followers of the user receive the other type of notification (see TRANSACTION_POST). Example:

{
  "kind": "OWN_TRANSACTION",
  "sender": <user_id>,
  "post": <transaction_post_id>
  ...
}

POST_FOLLOW_NEW_REPLY

This type of notification is created when some user (commenter) replies or leaves a comment on a post. The recipients of this notification are the followers of the post. Note that, to be considered as a follower the user can either explicitly follow a post or is automatically subscribed when replied to a post. The post owner receives another kind of norification (see REPLY_POST). Example:

{
  "kind": "POST_FOLLOW_NEW_REPLY",
  "sender": <commenter_id>,
  "post": <reply_id>
  ...
}

POST_LIKE

This type of notification is created when a user reacts to a post. The recipient of this notification is the author of the post. Example:

{
  "kind": "POST_LIKE",
  "sender": <user_who_reacted_id>,
  "post": <post_id>
  ...
}

PROFILE_POST

This type of notification is created when some user (author) creates a post on the other user's profile wall. The recipients of this notification are the followers of the user (i.e. profile wall owner). In other words, it notifies followers of the profile that a new post is added to the profile wall they follow. The wall owner receives another kind of notification (see. YOUR_PROFILE_POST). Example:

{
  "kind": "PROFILE_POST",
  "sender": <author_id>,
  "post": <post_id>
  ...
}

REPLY_POST

This type of notification is created when some user (commenter) replies or leaves a comment on a post. The recipient of this notification is the author of the post. Example:

{
  "kind": "REPLY_POST",
  "sender": <commenter_id>,
  "post": <reply_id>
  ...
}

THREAD_REPLY_POST

[Currently unused]

TRANSACTION_BULK_BUY

[Currently unused]

TRANSACTION_BULK_SELL

[Currently unused]

TRANSACTION_POST

This type of notification is created when the user makes a new transaction (and subsequently a transaction post is created). The recipients of this notification are the followers of the user. The user receives the other type of notification (see OWN_TRANSACTION). Example:

{
  "kind": "TRANSACTION_POST",
  "sender": <user_id>,
  "post": <transaction_post_id>
  ...
}

WEEKLY_REPORT

This type of notification is created when the weekly report is created for the user. Example:

{
  "kind": "WEEKLY_REPORT",
  "sender": <default_weekly_report_sender_id>,
  "profile": <user_profile_id>
  ...
}

YOUR_PROFILE_POST

This type of notification is created when some user (author) creates a post on another user's profile wall. The recipient of this notification is the owner of the profile wall. The follower of the profile wall receive another kind of notification (see PROFILE_POST). Example:

{
  "kind": "YOUR_PROFILE_POST",
  "sender": <author_id>,
  "post": <post_id>
  ...
}