1. Getting started with Claned webhooks
Webhooks are HTTP requests triggered by some event in a source system (in our case, Claned) and sent to a receiving system (your system). The most useful feature of webhooks is that they are automated, so that a request is sent from Claned to your system as soon as a relevant event occurs in Claned.
Webhooks are a great way to leverage Claned's external REST API to make your integration more performant, allowing for a much quicker data sync. Keep reading for instructions on how to get started with our webhooks in your own integration!
2. Open Claned and click on the "Admin" tab
3. Click on the "Advanced" tab
4. Navigate to the "Webhooks" section
This is where we will configure a webhook for your use. The section consists of three elements:
-
The secret key field
-
A webhook URL
-
Three events of your choice to be used in the webhook request
5. Secret key
Click the "Change" button to generate a secret key for your organization. A secret key ensures that requests sent to the endpoint URL are from Claned. Include the key in your integration code. Make sure to click "Save"!
6. Webhook URL
This is the destination endpoint URL on your system. If you haven't already, build an endpoint in your system and add the URL in the "Advanced" page as the Webhook URL. Once this is complete, you'll receive webhook requests at that endpoint whenever an event occurs. Make sure to click "Save"!
For testing purposes, you can use a site like https://webhook.site/ to generate an endpoint URL to receive and inspect requests. Open the webpage, copy the "Your unique URL", and paste it into the "Webhook URL" field in Claned. More on this in section 8. Testing webhooks.
7. Webhook events options
As of writing, Claned offers three webhooks. All three use the POST HTTP method:
-
new_board
-
new_board_grade
-
invitation_to_organization
Event: new_board
-
Triggers everytime a new board is created in your organization
Event: new_board_grade
-
Triggers when a new board grade has been recorded (eg. user passed an assessment, teacher grades an assessment)
Event: invitation_to_organization
-
Triggers when a user is invited to your organization
Click the box next to the webhooks you'd like to use to enable them for your organization. Make sure to click "Save"!
8. Testing webhooks
We'll be using the webhook testing site https://webhook.site/ to test things out. Once you've configured the above sections, in Claned's "Webhooks" section in the "Advanced" page, click "Test" to make a test request to your endpoint URL. In the testing site, you should receive a request on the left-hand side of the page. Click it to inspect the request.
9. Testing webhooks, continued
Each webhook has a particular request content. Make note of this content format when integrating the webhooks into your system.
10. Request content: new_board
11. Request content: new_board_grade
12. Request content: invitation_to_organization
13. Conclusion
Webhooks are a powerful tool to enable quick and efficient data exchange between Claned and your system. We're constantly working to improve and expand webhook functionality, so if you have any ideas or run into issues using webhooks, please contact support@claned.com.