The webhook feature allows you to create webhooks that notify your internal services of certain changes in Ans. Webhooks can be used without the API, however we advise to incorporate the webhook feature in the integration structure that you have developed between Ans and other platforms, such as a student information or archiving system.
The main difference between the API and webhooks is the degree of proactivity. With an API, you as an institution need to retrieve certain data out of Ans yourself. You are responsible for the timing of the requests to retrieve the data. A webhook will support you proactively to determine the timing of when to retrieve certain data out of Ans. If you use webhooks, you can exchange data between Ans and other platforms realtime.
If you want to retrieve results data out of Ans to insert it in your student information system, you could use the API to get this information. One of the possible requests that you could do is a GET Results on a specific assignment. Ans will show you all results. It's possible that you do not know when you need to do this request. Perhaps, a teacher has not yet graded all the results of an assignment. If you were to request the results via the API, you would need to check the results of your GET request and then check to see if all results are already graded.
If you use the webhook feature, you will be informed by Ans about particular changes at the exact moment that the change is made. It is possible to enable a webhook which listens to all changes on a certain object within Ans, for example results. The webhook will send a message with information on what has changed. For example, you can allow your teachers to use the reviews feature if they have finished grading their students. If a student has been graded, teacher can perform a review on the result, which approves or disapproves the result. On the moment the review was done, the webhook of the results is triggered. You will be informed proactively about a result which is ready to be sent to another platform, such as a student information system.
You can also use the webhook to create a trigger in a workflow, either within or outside of Ans. For example, if you have received the information via the webhook that all results have been graded for an assignment, you could open a publication via the API. Other workflows are possible as well.
It is also possible to create, update and delete webhooks via the API. This allows you to easily manage your webhooks in an automated way.
At this moment, webhooks are available for the following objects in Ans:
The following events can be configured in the webhook:
- All events
Ans provides different events which you can listen to. You can listen to all events, all events for a specific object or only one event for an object.
- All events: use '*' to listen to all events of all objects
- All events for one object: use the name of the objects, for example 'assignment', to listen to all events of that object.
- One event for one object: combine the object with the name of the event to listen to that specific combination. For example, 'assignment.update'.
To add a new webhook endpoint, follow the steps below.
- Click the account_circle icon at the top right.
- Select settings Settings.
- Click Webhook in the menu on the left.
- Click New Webhook.
- Fill in the URL field and Subscriptions field and click Save.
- The URL field is used for the webpage where the information of the webhook is sent to. As mentioned above, we advise to use the webhook feature in combination with the API. You can fill in the URL of your enterprise service bus here.
- The subscriptions field is the combination of object(s) and event(s) which your webhook will listen to.
Once your webhook is created, you can click on the URL of the webhook. After that, click Webhook settings in the menu on the right. In the example that is used in the screenshots of this article, we've created a webhook which listens to all events of assignments. As you can see in the screenshot below, the webhook can be disabled and deleted if desired.
To see what an event looks like, click on Events in the menu on the right. In this menu, you see an overview of all events which triggered the webhook. Webhook events are stored for 14 days. You can click on an event to check the content. As you can see in the screenshot below, an event consists of the following parts:
- Timestamp: The moment of the event trigger
- Response: The status for delivery. In the example, a fake URL is used. Therefore, the response is scheduled for delivery.
- Payload changes: An overview of all changes in the object. In this case, the name of the assignment was updated from 'abc' to 'abcdef'. It can happen that multiple changes are visible here.
- Payload: In this field an overview of the object with the most actual information is visible. As you can see, the name of the assignment has changed here.