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.
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.
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.
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.
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.
When users are tagged in a comment, the information is stored in a list called
mentions. Each object in that list
has the following structure.
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.
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.
All changes to the Comment object in the system fire an event which ends up on a queue.
The initial webhook event is usually sent within six seconds of the event source occurring.
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.
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.