Webhook

Webhook is a new HTTP-based callback function in iSpring Learn that allows you to receive event notifications in the format of a POST request. You no longer need to send API requests or poll the server. The server will automatically send the relevant payload to your webhook URL when the specified event occurs. You can simply track the changes. 

To set up the webhook, you need to subscribe to the events and have a service that will process notifications.

How It Works

1. The user registers a subscriber and specifies the URL to which messages will be sent. An account can have multiple followers.
   Use the request: POST /webhook/register
   
   
2. The user confirms the URL with a verification code. After receiving the code for the specified URL, the user confirms the URL.
   Use requests: POST /webhook/code/send and POST /webhook/confirm
   At this stage, the integration is active.
   
   
3. Once created, the subscriber is active and they can receive messages immediately. A subscriber can be enabled and disabled.
   Use requests: POST /webhook/disable and POST /webhook/enable
   
   
4. A subscriber can be permanently deleted.
   Use request: POST /webhook/remove
   
   
5. A subscriber’s settings can be changed. If you change the URL, it should be confirmed with a code.
   Use request: POST /webhook/settings/change
   
   
6. A user can submit a subscriber to be notified of specific iSpring Learn events. Within the same account, different subscribers can be subscribed to be notified of different events. A subscriber can only be subscribed to one type of event.
   Use the request: POST /webhook/subscribe
   
   
7. The user can unsubscribe the subscriber from the subscription.
   Use the request: POST /webhook/unsubscribe
   
   
8. The user can get a list of the subscriber's subscriptions and information about the subscriber.
   Use requests: GET /webhook/subscription/list and GET /webhook/subscriber/info

Sending Events

Events are sent sequentially as a list. The list includes only consecutive events of the same type. If there is an event of a different type, the sequence will be interrupted and a new sequence will start.
The service will return the 200 code. Other codes are considered a failure and the resending process will be started.

Event Resubmission

If the sending events fails, the service will try to resend them. This takes one day. While waiting for a new attempt, events that have occurred earlier will continue to accumulate. If the retry is successful, all events that accumulated during the time when the subscriber's service was unavailable will be sent in a row.

If messages were not delivered within a day, then the confirmation status of the callbackURL will change to unconfirmed. The status needs to be confirmed again. All events that accumulated during the attempts will be lost.

Signature

Webhooks signs requests to verify the sources of messages. For this, the secret setting is used. If the setting has been added, then every request sent by the webhook will have an X-Hub-Signature header.

This is formed in the following way: the body of the sent request is concatenated with the secret setting and then the resulting string is hashed using the SHA-256 algorithm. This hash is the content of the header.