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_TOKENevents:init:falsereset:falsestep_complete:truelevel_complete:truetutorial_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 aCODEROAD_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