feat: add edx certificate webhook by Anas12091101 · Pull Request #3459 · mitodl/mitxonline

Anas12091101 · 2026-04-06T12:41:44Z

What are the relevant tickets?

https://github.com/mitodl/hq/issues/10777

Description (What does it do?)

This PR adds a webhook API endpoint (POST /api/certificate_webhook/) that receives certificate creation events from an Open edX plugin. When edX creates a certificate, the plugin (WIP, see: mitodl/open-edx-plugins#684) sends the user's email and course run ID; this endpoint fetches the grade from edX, syncs it locally, and creates the corresponding certificate in MITx Online.

Screenshots (if appropriate):

Desktop screenshots
Mobile width screenshots

How can this be tested?

1. Set up OAuth2 credentials

Create an OAuth2 access token in Django admin (/admin/oauth2_provider/accesstoken/) or use an existing access token.

2. Prerequisites

Ensure the user has a verified enrollment in the course run, and the course run exists in edX with a passing grade for the user.

3. Test certificate creation (201)

curl -s -w "\nHTTP_STATUS: %{http_code}\n" -X POST \
  http://localhost:9080/api/process_certificate_webhook/ \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<user_email>", "course_id": "<course_run_courseware_id>"}'

Expected response:

{"certificate_status": "created"}
HTTP_STATUS: 200

4. Test idempotency — duplicate call (200)

Run the same curl command again. Expected response:

{"certificate_status": "exists"}
HTTP_STATUS: 200

5. Test unauthenticated request (401)

curl -s -w "\nHTTP_STATUS: %{http_code}\n" -X POST \
  http://localhost:9080/api/process_certificate_webhook/ \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test@example.com", "course_id": "course-v1:MITx+1+2024"}'

Expected: HTTP_STATUS: 401

6. Test missing fields (400)

curl -s -w "\nHTTP_STATUS: %{http_code}\n" -X POST \
  http://localhost:9080/api/process_certificate_webhook/ \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test@example.com"}'

Expected: HTTP_STATUS: 400 with error about missing course_id.

Additional Context

github-actions · 2026-04-06T12:42:04Z

OpenAPI Changes

Show/hide ## Changes for v0.yaml:

## Changes for v0.yaml:
No changes detected

## Changes for v1.yaml:
No changes detected

## Changes for v2.yaml:
No changes detected

Unexpected changes? Ensure your branch is up-to-date with main (consider rebasing).

sentry · 2026-04-06T12:47:02Z

+    def test_missing_fields_returns_400(
+        self, user_drf_client, payload, expected_error_field
+    ):
+        """Test that missing required fields return 400"""
+        response = user_drf_client.post(
+            self.WEBHOOK_URL,
+            payload,
+            format="json",
+        )
+        assert response.status_code == status.HTTP_400_BAD_REQUEST


Bug: The call to get_edx_grades_with_users in the webhook path is not wrapped in an exception handler, which can lead to unhandled exceptions from the external grades API.
_{Severity: HIGH}

Suggested Fix

Wrap the get_edx_grades_with_users(run, user=user) call in the webhook path with the exception_logging_generator, similar to how it is handled in the periodic task path. This will ensure exceptions from the external API are caught and logged, preventing 500 errors.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: openedx/views_test.py#L57-L66 Potential issue: In the webhook path for certificate generation, the call to `get_edx_grades_with_users` is not wrapped in an exception handler. This function makes an external API call to the edX grades service. If this external call fails due to network issues, an invalid `user.edx_username`, or other API errors, the exception will propagate unhandled. This will cause the webhook endpoint to return a 500 server error instead of gracefully handling the failure.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

arslanashraf7 · 2026-04-16T13:13:40Z

+    """
+
+    authentication_classes = [OAuth2Authentication]
+    permission_classes = [IsAuthenticated]


Should be admin level permissions. IsAdminUser

arslanashraf7 · 2026-04-16T14:53:38Z

+        if is_webhook:
+            # Webhook: fetch grade for the specific user only
+            edx_grade_user_iter = get_edx_grades_with_users(run, user=user)
+        else:
+            edx_grade_user_iter = exception_logging_generator(
+                get_edx_grades_with_users(run)
+            )


Don't need this condition if the passed user is None. So, in both cases, we should be able to do get_edx_grades_with_users(run, user=user) where when user=None, it would automatically run for every user.

arslanashraf7 · 2026-04-16T14:54:23Z

            0,
        )
-        for edx_grade, user in edx_grade_user_iter:
+        for edx_grade, run_user in edx_grade_user_iter:


nit: this rename isn't needed really.

arslanashraf7 · 2026-04-16T15:01:51Z

+                if created:
+                    certificate_status = "created"
+                elif certificate:
+                    certificate_status = "exists"


Aren't they always going to be available together? I checked process_course_run_grade_certificate and it would only return a certificate object when it creates one.

arslanashraf7 · 2026-04-16T15:11:14Z

+        certificate_status = generate_course_run_certificates(
+            user=user,
+            course_run=course_run,
+            is_webhook=True,
+        )
+
+        response_status = (
+            status.HTTP_201_CREATED
+            if certificate_status == "created"
+            else status.HTTP_200_OK
+        )


The idea of the webhook is to trigger the processing of the certificate. I don't think we specifically need to return the created/deleted status from the actual certificate creation. So, if a valid request is received, it would return 200 that the request if being processed.
Additionally, Open edX is not going to look for the actual status and do something about it unless it is 40x or 50x.

arslanashraf7 · 2026-04-16T15:12:04Z

-    if course_runs is None or course_runs.count() == 0:
-        log.info("No course runs matched the certificates generation criteria")
-        return
+    certificate_status = None


No need for this certificate_status = None and the related complexity, The view should just call this method and assume the certificate processing started.

arslanashraf7 · 2026-04-16T15:12:17Z

        name="openedx-private-oauth-complete-no-apisix",
    ),
+    path(
+        "api/certificate_webhook/",


Suggested change

"api/certificate_webhook/",

"api/process_certificate_webhook/",

arslanashraf7 · 2026-04-16T15:12:32Z

    return HttpResponse(status=status.HTTP_200_OK)
+
+
+class CertificateWebhookView(APIView):


Suggested change

class CertificateWebhookView(APIView):

class ProcessCertificateWebhookView(APIView):

arslanashraf7 · 2026-04-16T15:14:18Z

+            course_run_id,
+        )
+
+        certificate_status = generate_course_run_certificates(


At this point, the view can check for an existing certificate before calling generate_course_run_certificates for idempotency.

arslanashraf7 · 2026-04-24T10:11:52Z

+    if is_webhook and user and course_run:
+        course_runs = [course_run]


Now that I think more about this, it would be kind of an anti-pattern. e.g., if someone is passing a course_run explicitly, we should still let them do the desired thing. So, if a run or a user is passed, the function should work on that independently. The webhook check is just to bypass the conditions below. In fact, I think the name of this boolean should be bypass_validation or force, which will allow running the cert generation without the dates and eligibility check.

In the end, I think we should handle every parameter separately:

If a course run is passed, we process only that course run

If a user is passed, we process only that user

If bypass_validation or force is passed, we bypass the dates, eligibility, etc. checks
This way the method would be more flexible.

arslanashraf7 · 2026-04-24T10:18:35Z

+    permission_classes = [IsAdminUser]
+
+    def post(self, request):
+        user_email = request.data.get("user_id")


Also let's call it email:

Suggested change

user_email = request.data.get("user_id")

user_email = request.data.get("email")

@Anas12091101 This still needs to be applied.

arslanashraf7 · 2026-04-29T10:01:46Z

+    Hits the edX grades API and generates the certificates and grades for users for course runs.
+
+    Each parameter works independently:
+    - If course_run is provided, only that course run is processed (skipping eligibility filtering).


Suggested change

- If course_run is provided, only that course run is processed (skipping eligibility filtering).

- If course_run is provided, only that course run is processed (skipping course runs eligibility filtering).

arslanashraf7 · 2026-04-29T10:03:21Z

+                if len(course_runs) == 1:
+                    return


No need for this check. If there is just one course run in the loop, it will automatically stop at this point after continue.

arslanashraf7 · 2026-04-29T10:05:26Z

        name="openedx-enrollment-webhook",
    ),
+    path(
+        "api/process_certificate_webhook/",


Let's make the URL pattern similar to "api/openedx_webhook/enrollment/" above, to keep it standard with other webhook(s).

arslanashraf7 · 2026-04-29T10:12:49Z

+    authentication_classes = [OAuth2Authentication]
+    permission_classes = [IsAdminUser]
+
+    def post(self, request):


Let's add more log statements in different code paths. Currently there is no log in the application that tells what happened to the request.

arslanashraf7 · 2026-04-29T10:14:17Z

+        log.info(
+            "Certificate webhook received for user %s, course run %s",
+            user_email,
+            course_run_id,
+        )


This log should be at the start of the view, indicating that the webhook request has been received. In this place, we can log something like "Validation completed, the webook will be processed. etc"

arslanashraf7 · 2026-04-29T12:49:32Z

+@extend_schema(exclude=True)
+class ProcessCertificateWebhookView(APIView):


nit: let's use decorator based functional view here as well just like we did in enrollment webhook.

for more information, see https://pre-commit.ci

sentry Bot reviewed Apr 6, 2026

View reviewed changes

Anas12091101 force-pushed the anas/add-edx-certificate-webhook branch from 43b0d69 to fabb512 Compare April 6, 2026 15:13

Anas12091101 added the Needs Review label Apr 7, 2026

arslanashraf7 self-assigned this Apr 16, 2026

arslanashraf7 requested changes Apr 16, 2026

View reviewed changes

arslanashraf7 added Waiting on Author and removed Needs Review labels Apr 16, 2026

Anas12091101 force-pushed the anas/add-edx-certificate-webhook branch 2 times, most recently from af3f215 to 1d62ba6 Compare April 20, 2026 12:30

sentry Bot reviewed Apr 20, 2026

View reviewed changes

Comment thread openedx/views.py

Comment thread courses/api.py Outdated

Comment thread courses/api.py

Anas12091101 force-pushed the anas/add-edx-certificate-webhook branch from f065d19 to 2ae2863 Compare April 20, 2026 14:30

Anas12091101 requested a review from arslanashraf7 April 20, 2026 14:50

Anas12091101 added Needs Review and removed Waiting on Author labels Apr 20, 2026

arslanashraf7 requested changes Apr 24, 2026

View reviewed changes

arslanashraf7 added Waiting on Author and removed Needs Review labels Apr 24, 2026

arslanashraf7 requested changes Apr 24, 2026

View reviewed changes

Anas12091101 force-pushed the anas/add-edx-certificate-webhook branch from ca0bcfd to 22ff4d4 Compare April 24, 2026 16:19

Anas12091101 requested a review from arslanashraf7 April 27, 2026 06:55

Anas12091101 added Needs Review and removed Waiting on Author labels Apr 27, 2026

arslanashraf7 requested changes Apr 29, 2026

View reviewed changes

arslanashraf7 added Waiting on Author and removed Needs Review labels Apr 29, 2026

arslanashraf7 mentioned this pull request Apr 29, 2026

feat: add event handler webhook for certificate generation mitodl/open-edx-plugins#684

Open

2 tasks

Anas12091101 added 3 commits April 30, 2026 17:32

feat: add edx certificate webhook

65c3dd1

fix: pre-commit

f4afc03

fix: issues

dd14d3e

Anas12091101 added 4 commits April 30, 2026 17:32

fix: issues

1440393

fix: issues

0fe052f

fix: issues

a612730

fix: issues

d3c56a0

Anas12091101 force-pushed the anas/add-edx-certificate-webhook branch from 67b2ede to d3c56a0 Compare April 30, 2026 12:33

[pre-commit.ci] auto fixes from pre-commit.com hooks

a28ffe4

for more information, see https://pre-commit.ci

Anas12091101 added Needs Review and removed Waiting on Author labels May 4, 2026

Anas12091101 requested a review from arslanashraf7 May 4, 2026 11:10

	"api/certificate_webhook/",
	"api/process_certificate_webhook/",

		return HttpResponse(status=status.HTTP_200_OK)


		class CertificateWebhookView(APIView):

	class CertificateWebhookView(APIView):
	class ProcessCertificateWebhookView(APIView):

		if is_webhook and user and course_run:
		course_runs = [course_run]

	user_email = request.data.get("user_id")
	user_email = request.data.get("email")

	- If course_run is provided, only that course run is processed (skipping eligibility filtering).
	- If course_run is provided, only that course run is processed (skipping course runs eligibility filtering).

		@extend_schema(exclude=True)
		class ProcessCertificateWebhookView(APIView):

Conversation

Anas12091101 commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What are the relevant tickets?

Description (What does it do?)

Screenshots (if appropriate):

How can this be tested?

Additional Context

Uh oh!

github-actions Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenAPI Changes

Uh oh!

sentry Bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Anas12091101 commented Apr 6, 2026 •

edited

Loading

github-actions Bot commented Apr 6, 2026 •

edited

Loading