Copy page

Example apps

Webhooks: GitHub Webhook Receiver

Webhooks, also called reverse APIs, are how a service sends real-time data to other applications the moment a specific event occurs, instead of those applications polling for changes. Events arrive in bursts and are silent in between, so a receiver that scales to zero and wakes in milliseconds costs nothing while it waits.

This example shows how to build a simple GitHub Webhook receiver using Node.js with Express and run it on Unikraft Cloud. In this case, the webhook receiver listens for GitHub events, such as push events or pull request events, and logs them to the console.

To run this example, follow these steps:

1. Install the unikraft CLI. You need a BuildKit builder. The easiest way to get one is via Docker. Alternatively, you can also directly set up and use BuildKit, see the quick start.

2. Clone the examples repository and cd into the examples/github-webhook-node/ directory:

   Code
   git clone https://github.com/unikraft-cloud/examples
   cd examples/github-webhook-node/

Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

Code
unikraft login

When done, invoke the following command to deploy this app on Unikraft Cloud:

Code
unikraft build . --output <my-org>/github-webhook-node:latest
unikraft run --metro fra \
  -m 1G \
  -p 443:3000/tls+http \
  --scale-to-zero policy=on,cooldown-time=1000,stateful=true \
  -e GITHUB_WEBHOOK_SECRET=your_secret_here \
  --image <my-org>/github-webhook-node:latest

GITHUB_WEBHOOK_SECRET is the secret used to verify incoming webhook requests from GitHub. Set it to a string with high entropy.

The output shows the instance address and other details:

Code
metro:        fra
name:         github-webhook-node-bzq7u
uuid:         8a8634f1-fc78-4cc0-aa36-8f082d8a59f5
state:        starting
image:        <my-org>/github-webhook-node
resources:
  memory:     1024MiB
  vcpus:      1
service:
  uuid:       67c7cca2-ca82-1467-e2f1-1b455edb638c
  name:       dry-cloud-uuw0qlb6
  domains:
  - fqdn:     dry-cloud-uuw0qlb6.fra.unikraft.app
networks:
- uuid:       6153b689-b713-97c3-f8bb-bd08cc47f6bc
  private-ip: 10.0.1.205
  mac:        12:b0:d0:97:b0:d2
timestamps:
  created:    just now

In this case, the instance name is github-webhook-node-bzq7u and the address is https://dry-cloud-uuw0qlb6.fra.unikraft.app. They're different for each run.

Use curl to query the Unikraft Cloud instance of the Node.js webhook server's health endpoint:

Code
curl https://dry-cloud-uuw0qlb6.fra.unikraft.app/health

Code
{"status":"healthy","timestamp":"2025-12-17T14:55:20.953Z","uptime":0.063799807}

The uptime field is so small because Unikraft Cloud scales the instance to zero when no connections are active. When a request comes in, Unikraft Cloud automatically starts the instance.

To see the incoming webhook events (you set up the webhook in GitHub), you can retrieve the logs of the instance by running:

Code
unikraft instances logs github-webhook-node-bzq7u

Code
[2025-12-17T15:20:54.524Z] Webhook received: ping
{
  "timestamp": "2025-12-17T15:20:54.524Z",
  "event": "ping",
  "data": {
    "zen": "Accessible for all.",
    ...
  },
  "receivedAt": 1765984854525
}
...

GitHub sends the ping event when you set up the webhook. You can list information about the instance by running:

Code
unikraft instances list

Code
METRO  NAME                       STATE    IMAGE                         ARGS  MEMORY  VCPUS  FQDN                                 CREATED
fra    github-webhook-node-bzq7u  standby  <my-org>/github-webhook-node        1.0GiB  1      dry-cloud-uuw0qlb6.fra.unikraft.app  2 minutes ago

When done, you can remove the instance:

Code
unikraft instances delete github-webhook-node-bzq7u

Test GitHub webhooks

To test the GitHub webhook receiver, you must set up a webhook in a GitHub repository. Make sure to set the payload address to the Unikraft Cloud instance webhook, in this case https://dry-cloud-uuw0qlb6.fra.unikraft.app/webhook/github. You should also set the content type to application/json and select the events you want to receive. Lastly, you should set the secret to verify that the requests come from GitHub and weren't tampered with. Now, once you make changes in the repository (that you are listening to), you should see the webhook events logged in the instance logs:

Code
unikraft instances logs github-webhook-node-bzq7u

Code
[2025-12-17T17:28:51.136Z] Webhook received: push
{
  "timestamp": "2025-12-17T17:28:51.136Z",
  "event": "push",
  "data": {
    "ref": "refs/heads/main",
    "before": "3312f99896b85e896f730d246180979553748f9d",
    "after": "12b2962bbc70f92fa33e4b30c0e1a3ed5f35f9d4",
    "repository": {
      "id": 123456789,
      "name": "your-repo",
      ...
    },
    ...
  },
  "receivedAt": 1765992531136
}

Customize your app

To customize the app, update the files in the repository, listed below:

• server.js: The Node.js Express web server that handles GitHub webhook events
• Kraftfile: the Unikraft Cloud specification
• Dockerfile: the Docker-specified app filesystem

Learn more

Use the --help option for detailed information on using Unikraft Cloud:

Code
unikraft --help

Or visit the CLI Reference.