Welcome back! So far, you have learned how to set up a FastAPI backend, manage changesets, and handle errors and validation in your Code Review Assistant project. In this lesson, we will take the next step by connecting your application to GitHub using webhooks.
A webhook is a way for one application to send real-time data to another application when a specific event happens. In our case, we want GitHub to notify our Code Review Assistant whenever someone opens or updates a pull request. This allows us to automatically start a code review process as soon as new code is submitted.
By the end of this lesson, you will know how to receive GitHub webhook events, verify their authenticity, extract pull request data, and trigger your code review workflow — all automatically.
Before we dive in, let’s quickly remind ourselves how FastAPI handles HTTP requests. In previous lessons, you learned how to define endpoints using FastAPI and how to read data from incoming requests.
For example, to create a POST
endpoint and read the request body, you might write:
Here, @app.post("/example")
defines a POST
endpoint. The request: Request
parameter allows you to access the raw request, and await request.json()
reads the JSON body sent by the client.
This pattern is the foundation for receiving webhook events, which are just HTTP POST
requests sent by GitHub to your application.
Let’s start by creating a FastAPI endpoint that can receive webhook events from GitHub.
First, we need to define a POST
endpoint. Since GitHub sends the webhook data as a raw payload, we will read the body as bytes:
@router.post("/webhook/github")
creates a newPOST
endpoint at/webhook/github
.payload = await request.body()
reads the raw bytes sent by GitHub. This is important because we may need the exact bytes for signature verification.
At this point, your application can receive webhook events from GitHub. However, we need to make sure these events are actually coming from GitHub and not from someone else.
Security is important. GitHub allows you to set a secret when configuring a webhook. When GitHub sends a webhook event, it includes a signature in the headers. Your application should verify this signature to make sure the request is genuine.
Here’s how you can verify the signature using HMAC
and SHA-256
:
payload
is the raw request body.signature
is the value from theX-Hub-Signature-256
header.secret
is the webhook secret you set in GitHub.
To use this in your endpoint:
If the signature is invalid, the endpoint returns a 401 Unauthorized
error. This helps protect your application from unwanted or malicious requests.
Once you have verified the webhook, you need to extract the pull request information from the payload. GitHub sends the data as JSON, so you can parse it like this:
event = json.loads(payload)
parses the JSON payload.- We check if the action is
'opened'
or'synchronize'
, which are the events we care about for new or updated pull requests. - We extract the pull request title, description, author, and the URL to the diff.
Example Output:
This information is essential for tracking changes and starting the review process.
Now that you have the pull request data, you need to save it in your database and schedule a code review. In previous lessons, you learned how to use SQLAlchemy
models for changesets. Here’s how you might use them in this context:
- We create a new
Changeset
object with the pull request data. - We add and commit it to the database.
- We use
background_tasks.add_task()
to schedule the review process without blocking the webhook response.
This approach ensures that your application quickly responds to GitHub and then processes the review in the background.
In this lesson, you learned how to connect your Code Review Assistant to GitHub using webhooks. You saw how to:
- Set up a FastAPI endpoint to receive webhook events.
- Verify webhook signatures for security.
- Parse pull request data from the webhook payload.
- Store changeset information and schedule background review tasks.
These steps allow your application to automatically react to new or updated pull requests, making your code review process faster and more reliable.
In the next practice exercises, you will get hands-on experience with each of these steps. You will implement and test webhook handling, signature verification, and changeset storage. This will help you solidify your understanding and prepare you for more advanced integrations in the future.
