Webhooks

Webhooks

Overview

Webhook actions allow you to automatically send requests to an API when specific events occur on the platform. You can use Webhook actions to connect your CYPHER platform with third-party services, your own servers, or CYPHER Learning APIs.

For example, you can configure a Webhook action to send a request when a learner completes a course, allowing you to automatically trigger an action or exchange data with another system.

This article covers the basics of adding and configuring a Webhook action for a qualifying event.

Installing the Webhooks app

To use Webhooks, the app must first be installed. To install the Webhooks app, administrators:

  1. Click Admin from the primary navigation menu.
  2. Click App center from the fly-out menu.
  3. Install the Webhooks app from the Integration tools section. 
Admin, App center with the Webhooks app highlighted

Webhooks actions

After installing the Webhooks app, the Webhook action becomes available on the Integrations tab any time you add a rule action.  You can add webhook rules to course enrollments; course, module, and section completions, when users join a group; account creation; and more. 

To add a webhook action:
  1. Click Add in the action section of a qualifying event.
    1. For more details on adding actions to qualifying events, visit the Rules knowledge based article.
  2. Click the Integrations tab.
  3. Click Webhook.

Add action pop-up, Integrations tab with the Webhook button highlighted

The Webhook pop-up displays, where you can configure the details of the webhook. To begin:
  1. Enter a webhook Endpoint, which specifies where the request is sent and can specify what data to retrieve.
    1. The Endpoint can be HTTP or HTTPS. 
    2. There is a 256 character limit for the endpoint.
    3. The Endpoint can include variables, just like message templates. The available variables are listed at the top of the Webhook pop-up.
  2. Select a webhook Method,  which specifies the HTTP method used to send the webhook request to the endpoint.
    1. Select  POST to send or create data, GET to retrieve data,  PATCH to update data, or DELETE to remove data.
Webhook pop-up with the Method drop-down menu active
  1. Select a Content type, which specifies the format of the data sent in the webhook request. Choose from:
    1. application/x-www-form-urlencoded
    2. application/json
    3. application/xml
  2. Enter the webhook Body, which specifies the data sent to the webhook endpoint as part of the request. The format of the body should match the selected Content type and the requirements of the receiving API.
    1. The Body can accept variables, just like message templates. The available variables are listed at the top of theWebhook pop-up.
    2. A body is typically not required when using the GET method.
  3. If you only want the webhook action to occur for specific users, you can add a filter. To add a filter, click the Add  icon in the Filters section.
    1. To learn more about filters, visit the Filters knowledge base article. 
  4. Click Save.

Idea
You can add multiple Webhook actions to qualifying events. 

Webhooks widget

For additional visibility into webhook calls and errors, administrators can add the Webhooks widget to the Admin dashboard.

To add the widget to the dashboard:
  1. Click Home from the primary navigation menu.
  2. Click the Admin tab.
  3. Click the Edit widgets  button.
Admin dashboard with the Edit widgets button highlighted

The Edit pop-up displays.

  1. Click Center panel.

The Edit pop-up with the Center panel button highlighted

The Admin dashboard will display in edit mode.

  1. Drag-and-drop the Webhooks widget from the Available widgets column to the Center panel.
  2. Click Save. 

The Admin dashboard in edit mode with the Webhooks widget being drug to the Center panel

The Webhooks widget displays the number of Webhook calls and the number of errors.

The Admin dashboard with the Webhooks widget highlighted

Additional information and troubleshooting 

  1. Webhook jobs allow a full 10 seconds for a webhook to respond to the call from CYPHER Learning's job servers. If the server that is called by a webhook does not respond within 10 seconds, the connection will terminate with the remote service, wait for five seconds, then attempt to invoke the webhook again. The system will repeat this retry logic up to 10 times, doubling the delay each time (5s, 10s, 20s, 40s, 80s, etc.) before registering the entire operation as failed due to timeout.
  2. The platform automatically applies URL encoding. When entering endpoints, make sure to use a decoded URL to prevent double encoding.
    1. For example, if your endpoint includes encoded characters such as %2F, replace the %2F-encoded component with the decoded character of / so the endpoint just contains the decoded URL.
    2. The HTML URL Encoding Reference is a great resource to assist you in decoding an encoded URL.