lookit / lookit/lookit-api

webhook/integration to mark responses as scheduled/complete

Open
#1,873 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
12
Forks
21
Avg merge
5d 19h
Merged PRs (30d)
5

Description

## Summary

For external and hybrid studies, it's difficult for researchers to see which of their CHS responses (1) resulted in a scheduled sync session (vs someone checking the calendar and not scheduling), or (2) completed an external/hybrid async session. It would be nice if we had webhooks to update the response based on these external events:

- "Scheduled" event for an external synchronous study, i.e. person did not just visit the booking page but actually made an appointment. (For a number of reasons, we are not going to capture whether or not the actual scheduled session was completed, but we do provide the researcher-controlled dropdown fields for that).
- "Completed" event for external asynchronous study
- "Completed" event for external portion of hybrid study

## Implementation

The webhooks for all of these could be implemented in the same way: create a unique code to use for marking a response as completed/scheduled, and add an API endpoint that passes that code along with the response ID (and maybe study ID). The unique code could be a hash of the study and response IDs, which prevents bad actors from directly calling the completion webhook with just a response and/or study ID (which are public). The code could either be a property that is accessed as needed (reproducible via hashing), or a stored value that would require adding a new field to the study or response model/table.

We could use this webhook to update the existing "completed" field for Responses, which is always FALSE for external studies and internal hybrid studies. But it might be better to add a separate "webhook completion" field to the Response model/table that stores a timestamp value.

## Questions

What booking sites are the most common (Calendly, etc.)?

How easy/hard is it to get these platforms to call a custom API endpoint upon the successful scheduling of an appointment?

If it's very hard to set up, or if it's only available as a paid feature on those sites, we could consider introducing a "scheduled" study type that works like an internal study but where we have more control over the scheduling site/actions (maybe by integrating a specific scheduling tool, or presenting any of them in an iframe?). This might make it easier to add the webhook ourselves, so that the researcher doesn't need to set it up. If we go this route, we would need to make sure that this "internal/scheduled" study type is still correctly categorized as "external" within our system!

Contributor guide

Open the contributing guide

Research direction

Start with the Response model/table and the API endpoint described in the implementation section. Resolve whether scheduled and completed events need separate fields, how the unique code is generated or stored, and which external booking services can call the endpoint. Done means the event scope, security model, storage choice, and endpoint behavior are agreed and documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.