Webhooks are a way to listen to changes in the application. When you register a webhook endpoint and set up a subscription, Ans will send an event to the endpoint if a change occurred in the application.
You can use these events to perform a new action, for example:
- Archive results when an assignment is archived
- Add users after an assignment is created
- Export a result after it has been approved
When creating a webhook you can specify which events you want to listen to. You can listen to all events, all events for a specific object or only one event for an object.
You can listen to 'create', 'update' and 'destroy' events on an object or a combination for example:
- '*' - all events for all objects - 'assignment' - All events for an assignment - 'assignment.update' - Only notify when an assignment is updated
The following objects are currently supported:
- Assignment - Result
Create a webhook via the API.
A webhook can be created through the interface or via the API.
To create a webhook via the API, a POST request must be made to:
The attributes for creating webhooks are listed in the schema section of the webhook documentation. Additional information about setting up the webhook through the Ans API can be found in the top section of the API documentation under “Webhooks”.
The webhooks API returns a secret after creating a new webhook. This secret can be used to verify that the webhook call comes from Ans by creating a sha256 HMAC with the request body and this secret and comparing it to the X-Ans-Signature Header.
Webhook requests are automatically retried up to five times if the endpoint returns a response code other than 2xx. The request will also be retried if the request returned an SSL error or resulted in a Timeout. In case of a connection error, we assume the endpoint is no longer active and the webhook endpoint will be disabled. With the endpoint disabled, we will no longer send events to that webhook endpoint. You can always reenable the endpoint via the API or through the interface if the endpoint needs to become active again.
The time interval between retries is gradually extended by multiplying the retry count with a random jitter (between 30 seconds and 10 minutes).
Every webhook event is logged and contains the response code, headers and body of the response for debugging purposes. When an event failed to deliver and is being retried, we only store the response of the latest retry.