Webhooks are a way for apps to communicate between them automatically.

Requirements

• default url
• optional url overwrites
• token based authentication

Config

CodeRoad could send HTTP POST requests to a target endpoint based on desired events. A Webhooks can be specified in the CodeRoad config.

config:
  webhook:
    endpoint: “https://api.com/api/v1/coderoad”
    headers:
      x-token: $CODEROAD_WEBHOOK_TOKEN
    events:
      init: false
      reset: false
      step_complete: true
      level_complete: true
      tutorial_complete: true

Event

An suggested example webhook POST request

{
  "type": “step_complete”,
  "levelId": “some-level-id",
  "stepId": “some-step-id”,
  "tutorialId": "some-tutorial-id"
}

Authentication

Authentication: we will need a standardized format for using a CODEROAD_WEBHOOK_TOKEN, perhaps a global string variable that can be passed in and evaluated.

Ideally not having to interpret a string, like "Bearer $CODEROAD_WEBHOOK_TOKEN", would save some development time.

Follow Up

This proposal could later be followed up with:

• webhook error handling
• retry strategy
• batch processing

I have a few questions about using level/step ids. If a tutorial is changed, these will update. The webhook API would be expected to understand which level/step id it is mapped to. Let me know if this is a problem.

Resources

• docs: https://coderoad.github.io/docs/hooks-actions
• hooks for events: https://github.com/coderoad/coderoad-vscode/blob/master/src/services/hooks/index.ts

@raisedadead @moT01