With FastComments it's possible to invoke an API endpoint whenever a comment gets added, updated, or removed from our system.

We accomplish this with asynchronous webhooks over HTTP/HTTPS.

What are Webhooks Internal Link

A Webhook is a mechanism, or an integration, between two systems where the "producer" (FastComments) fires an event that the "consumer" (You) consumes via an API call.

Supported Events & Resources Internal Link

FastComments supports webhooks for the Comment resource only.

We support webhooks for comment creation, removal, and on update.

Each of these are considered separate events in our system and as such have different semantics and structures for the webhook events.

Setup Internal Link

First, navigate to the Webhooks admin. This is accessible via Manage Data -> Webhooks.

The configuration page appears as follows:

Webhooks Configuration

In this page you can specify endpoints for each type of comment event.

For each type of event, be sure to click Send Test Payload to ensure you've set up your integration correctly. See the next section, "Testing", for details.

Testing Internal Link

In the Webhooks admin there are Send Test Payload buttons for each event type (Create, Update, Delete). The Create and Update events send a dummy WebhookComment object, while testing Delete will send a dummy request body with just an ID.

The test will make two calls to verify the response code for "happy" (correct API Key) and "sad" (invalid API key) scenarios.

When the test sends an invalid API key you should return a status code of 401 for the test to pass completely. If you don't correctly check the value of the token, you'll see an error.

This is to ensure that you properly authenticate the request.

Data Structures Internal Link

The only structure sent via webhooks is the WebhookComment object, outlined in TypeScript below.

The WebhookComment Object Structure

The "Create" Event Structure

The "create" event request body is a WebhookComment object.

The "Update" Event Structure

The "update" event request body is a WebhookComment object.

The "Delete" Event Structure

The "delete" event request body is a WebhookComment object, but only containing the id.

The WebhookComment Object
External Link
2interface WebhookComment {
3 id: string
4 urlId: string
5 url: string
6 userId: string
7 commenterEmail: string
8 commenterName: string
9 comment: string
10 commentHTML: string
11 parentId: string
12 date: UTC_ISO_DateString
13 votes: number
14 verified: boolean
15 verifiedDate: number
16 reviewed: boolean
17 avatarSrc: string
18 isSpam: boolean
19 aiDeterminedSpam: boolean
20 hasImages: boolean
21 pageNumber: number
22 approved: boolean
23 locale: string

HTTP Methods Used

Create and Update both use HTTP PUT and not POST!

Since all of our requests contain an ID, repeating the same Create or Update request should not create new objects on your side.

This means that these calls are idempotent and should be PUT events as per the HTTP specification.

Security & API Tokens Internal Link

In the request header we'll pass your API Secret in the parameter called "token".

If you do not properly check this parameter, your integration will not be marked Verified. This is a safeguard to ensure any integrations with FastComments are secure.

How it Works Internal Link

All changes to the Comment object in the system fire an event which ends up on a queue.

You can monitor this queue in the Webhooks admin in the event that your API goes down.

If a request to your API fails, we'll re-queue it on a schedule.

That schedule is 1 Minute * the retry count. If the call fails once, it'll try again in a minute. If it fails twice, it'll then wait two minutes, and so on. This is so that we don't overload your API if you are going down to load related reasons.

In Conclusion

This concludes our Webhooks documentation.

We hope you find the FastComments Webhook integration easy to understand and fast to set up.

If you feel you have identified any gaps in our documentation, let us know below.