Skip to content
line

API & Webhooks

REST API

Section titled “REST API”

The REST API can be enabled with the following configuration:

scoold.api_enabled = true
# A random string min. 32 chars long
scoold.app_secret_key = "change_to_long_random_string"

The API can be accessed from /api/* and the OpenAPI documentation and console are located at /apidocs. API keys can be generated from the “Administration” page and can be made to expire after a number of hours or never (validity period = 0). Keys are in the JWT format and signed with the secret defined in scoold.app_secret_key. API keys can also be generated with any JWT library. The body of the key should contain the iat, appid and exp claims and must be signed with the secret scoold.app_secret_key.

You can use the public endpoint http://localhost:8000/api to check the health of the server. A GET /api will return 200 if the server is healthy and connected to Para, otherwise status code 500 is returned. The response body is similar to this:

{
  "healthy": true,
  "message": "Scoold API, see docs at http://localhost:8000/apidocs",
  "pro": false
}

API clients can be auto-generated using Swagger Codegen. You can also explore the API documentation reference and generate the clients from there.

Explore API docs The API reference describes all available REST endpoints.

Webhooks

Section titled “Webhooks”

Webhooks are enabled by default in Scoold. To disable this functionality change your Scoold configuration:

scoold-application.conf
scoold.webhooks_enabled = false

If you are self-hosting Para, you need to also enable webhooks there using the same configuration option. You can add or remove webhooks in the “Administration” page. Webhooks can also be disabled and they will be disabled automatically when the target URL doesn’t respond to requests from Para.

Para will notify your target URL with a POST request containing the payload and a X-Webhook-Signature header. This header should be verified by the receiving party by computing Base64(HmacSHA256(payload, secret)).

Webhook events

Section titled “Webhook events”

The standard events emitted by Scoold are:

  • question.create - whenever a new question is created
  • question.close - whenever a question is closed
  • question.view - whenever a question is viewed by anyone
  • question.approve - whenever a question is approved by moderator
  • answer.create - whenever a new answer is created
  • answer.accept - whenever an answer is accepted
  • answer.approve - whenever an answer is approved by moderator
  • report.create - whenever a new report is created
  • comment.create - whenever a new comment is created
  • user.signin - whenever a user signs in to the system
  • user.signup - whenever a new user is created
  • user.search - whenever a user performs a search
  • revision.restore - whenever a revision is restored
  • user.ban - Pro whenever a user is banned
  • user.mention - Pro whenever a user is mentioned
  • question.like - Pro whenever a question is favorited

The event playloads for events user.signin, question.view and user.search contain extra information about the client which made the original request, e.g. IP address, User-Agent and Referrer headers.

Custom webhook events

Section titled “Custom webhook events”

In addition to the standard event, Para also sends webhooks to the following core (CRUD) events, for all object types: create, update, delete, createAll, updateAll, deleteAll.

You can subscribe to any of these custom events in Scoold using the REST API like so:

POST /api/webhooks
{
  "targetUrl": "https://myurl",
  "typeFilter": "revision",
  "urlEncoded": false,
  "create": true,
  "update": false,
  "delete": false,
  "createAll": true,
  "updateAll": false,
  "deleteAll": false,
  "customEvents": ["revision.create"]
}

This will create a new custom event revision.create which will fire whenever a new revision is created. This makes it easy to integrate Scoold with services like Zapier because it implements the RESTHooks best practices.

Finally, you can configure a webhook so that it is only fired when the payload matches a certain filter. A filter could contain one or more values of a property, e.g. tags:tag1,tag2. If the payload inside the webhook matches the filter, then the payload is sent to the target URL, otherwise it is ignored. Here are some examples of webhook property filters:

  • tags:tag1,tag2 - payload must contain a list property tags and it must have both tag1 and tag2 in it
  • tags:tag1|tag2 - payload must contain a list property tags and it must have either tag1 or tag2 in it
  • name:Gordon - payload must contain a String property and it must be Gordon
  • name:Gordon|Joe - payload must contain a String property and it must be either Gordon or Joe
  • tags:- - payload must contain a list or string property tags and it must be empty

For more details about webhooks, please read the ↗ Para docs on webhooks.