Skip to main content

Webhooks

Webhooks allow your application to receive notifications (by HTTP requests) from SlickComment when events happen.

Supported events#

  • comment.pending: after a comment is marked as "pending".
  • comment.approved: after a comment is marked as "approved".
  • comment.trashed: after a comment is marked as "trashed".
  • comment.deleted_by_user: after a comment is deleted by the user.
  • notification.new_reply: before SlickComment sends notification emails to users about a new reply, you can use this event to create user notifications in your app!
  • page.nb_comments_changed: when the number of published comments on a page is changed

Steps to receive webhooks#

  1. Decide which events you wish to receive notifications for.
  2. Create an HTTP endpoint (webhook endpoint) in your app.
  3. Enter your endpoint & enable webhooks for your site in the console.
  4. Make sure the endpoint is accessible (if you're developing locally, you can use https://ngrok.com/). You can quickly test it with our tool in the Console 🠦 Site 🠦 Webhooks 🠦 Testing.
  5. Make sure the endpoint returns 200 response status code when everything is alright.

Validate webhook requests#

When SlickComment sends requests to your endpoint, there will be a signature in the JSON content. Make sure you validate this signature before processing other data.

The signature is a sha256 hash of the timestamp that is sent along in the JSON. The secret used for hashing is from Console 🠦 Site 🠦 Webhooks 🠦 Settings 🠦 Webhook Secret

This is an example PHP code for validating the signature:

$hash = hash_hmac('sha256', $timestamp, $webhookSecret);
if ($hash !== $signature) {    // signature is invalid      } else {    // signature is valid}

General JSON structure#

Every webhook request will have JSON content similar to this

{  "alertId": 123,  "eventCode": "comment...",  "timestamp": 1640355452,  "signature": "signature...",  "data": {}}

The object data will have different structures for different events. See the sections below!

Structures of data by event#

comment.pending#

comment.approved#

comment.trashed#

comment.deleted_by_user#

The 4 events above has the same structure for data:

{  "site": {},  "page": {},  "comment": {}}

notification.new_reply#

{  "site": {},  "page": {},  "parentComment": {},  "reply": {},  "subscriberUserSsoIds": ["user-sso-id-1", "user-sso-id-2", "..."],  "subscriberGuestEmails": ["[email protected]", "[email protected]", "..."]}

Note: if a comment is posted by a guest userScId and userSsoId will be null.

page.nb_comments_changed#

{  "site": {},  "page": {}}

Resource structures examples#

Site#

{  "id": "site-id",  "name": "site name",  "nbComments": 100,  "nbPendingComments": 2,  "nbUnreadFlags": 3}

Page#

{  "id": "page Id",  "scId": "page SlickComment Id",  "title": "Page title",  "url": "Page url",  "nbPublishedComments": 10,  "nbPublishedRootComments": 4}

Comment#

{  "id": 1,  "content": "<p>comment content</p>",  "createdAt": "2021-12-30T16:08:07+00:00",  "moderationStatus": "approved",  "isPinned": false,  "isPublished": true,  "reactions": {    "upvote": 1,    "downvote": 0  },  "url": "https://example.com/page-id?_sc_cid=1",  "deletedByUserAt": null,  "user": {}}

User#

{  "scId":  2,  "ssoId": "user-sso-id",  "name":  "John Doe",  "email": "[email protected]",  "avatarUrl":  "https://example.com/johns-avatar.jpg",  "profileUrl": "https://example.com/user/john",  "nbComments":  10,  "nbPublishedComments": 9,  "nbReactionsCreated":  1,  "nbReactionsReceived": 2,  "nbFlagsCreated":  3,  "nbFlagsReceived": 4}

Comments