Use Webhooks to get eCoach to notify your system when events happen in eCoach - for example when a student completes a course.

The available fields you can retrieve data for include:

Participant (user)

  • ID
  • First Name
  • Last Name
  • Username
  • Email address

Course

  • ID
  • Code
  • Title

Group

  • ID
  • Name

Tracking Data (course completion)

  • ID
  • Score
  • Passed
  • Passing grade
  • Total time spent
  • Commenced
  • Completed

Initiator (enrolment)

  • ID
  • First Name
  • Last Name
  • Username
  • Email address

If Webhooks has been enabled on your campus, you can enable individual hooks in the settings section of eCoach.

To get started, head over to the Campus Settings page by clicking the link found in the main menu under your profile picture.

Then select the 'Integrations' tab. 

Follow these simple steps to configure your web hook:

Step 1: Add a Course Completed or Student Enrolled hook.

Step 2: Enter the URL of your API endpoint.

Step 3: Click the test button to make sure the webhook works. It will receive a tick if the request received a successful response. You should of course check that your API has functioned properly as well. - If there is an error you will see a small x and you can hover over the button to see more details.

Step 4: Enable the webhook.


Here is an example of a request:

POST https://yoursite.com/api/completion {

    "id": 173512,

    "commenced":"2017-02-08T10:30:27+11:00",

    "completed":"2017-02-08T10:30:27+11:00",

    "passed": true,

    "progress_percent": 100,

    "score": {"max":100,"min":0,"raw":95,"percentage":95},

    "score_percent": 95,

    "student_name": "Peter Student",

    "total_time": 12000,

    "group": {

        "id": 287,

        "name": "test"

    },

    "course": {

        "code": "",

        "id": 2465,

        "title": "Customer Service - Hub"

    },

    "user": {

        "username": "peter_student",

        "firstname": "Peter",

        "lastname": "Student",

        "email": "test@test.com.au",

        "avatar": "url.png",

  "active": true,

        "timezone": "Australia/Sydney",

        "id": 767

    }

}

Returns {"return_url": "https://yoursite.com/course/ABC101/home"}

Or for Student Enrolled:

POST https://yoursite.com/api/enrolment {

    "initiator": {

        "username": "themanager",

        "firstname": "The",

        "lastname": "Manager",

        "id": 999,

        "email": "manager@test.com"

    },

    "group": {

        "id": 999,

        "name": "Semester 1"

    },

    "course": {

        "code": “CO101”,

        "id": 999,

        "title": "Course Title"

    },

    "user": {

        "username": "silly_student",

        "firstname": "Silly",

        "lastname": "Student",

        "id": 999,

        "has_email": true,

        "active": true,

        "timezone": "UTC",

        "email": “student@test.com

    },

    "date": "2017-08-09T20:32:56+0000",

    "id": 18141,

    "permissions": [

        "study"

    ]

}

Completion Return URL

Optionally,  your API may return a JSON object with additional info. For a Course Completed webhook, you may return a return_url that the student will be directed to when they have completed the course.

When the student has completed the course, they will see this message, which will take them to the return url, or back to the ecoach dashboard if none is provided.

Security

You’ll want to determine that the request is genuine, and for that you can generate a secret token in the webhooks settings, and we will sign the header of the request with the hash of the request . You can use the secret token to confirm the authenticity of the request.

User-Agent: GuzzleHttp/6.2.1 curl/7.49.1 PHP/7.0.3

  Content-Type: application/json

  X-Hook-Signature: a5b66983f1f046ddc8b877295fb1896e07601d4ea6bd8882540cc130e8242a40

  Content-Length: 177

An example of the request headers your webhook will receive - note the X-Hook-Signature header.

To verify that the message is genuine, simply generate a SHA-256 HMAC of the request body, using the provided hook secret as the key, produce a hex digest, and compare it with the signature we provide in the X-Hook-Signature header.

Here is sample code for generating the HMAC in various languages. https://gist.github.com/thewheat/7342c76ade46e7322c3e 

Did this answer your question?