Webhooks

SkyPort does not currently expose a documented webhook product surface in the repository modules shown here. Keep this page conservative and use it for planning or future expansion notes only.

Current State

• do not document active webhook receivers or emitters unless they exist in code
• do not invent deployment callbacks
• use this page only if you need to explain that webhook support is not yet implemented SkyPort supports GitHub push webhooks to trigger automatic deployments and offers rolling update behavior for Docker-based deployments.

Webhook URL

• Route: POST <public-url>/api/v1/webhooks/github/:projectId
• Replace :projectId with the numeric project id from the Projects list.

Example:

https://skyport.example.com/api/v1/webhooks/github/42

Public URL

• Production: set SKYPORT_PUBLIC_URL to your server's public URL (recommended).
• Local / testing: use a tunnel (eg. ngrok http 8080) and use the returned https URL.

Securing the webhook

• Set a shared secret in the SkyPort server environment:

GITHUB_WEBHOOK_SECRET="your-secret-here"

• In GitHub webhook settings set the same Secret. When GITHUB_WEBHOOK_SECRET is configured SkyPort verifies the X-Hub-Signature-256 header.

If the secret is not configured the webhook endpoint will still receive payloads but signatures will not be validated.

Example (unsigned)

curl -X POST -H "Content-Type: application/json" \
  -d '{"ref":"refs/heads/main","after":"<commit-sha>"}' \
  https://skyport.example.com/api/v1/webhooks/github/42

Rolling updates (zero downtime)

SkyPort supports rolling updates for deployments using the docker strategy. Key behaviour and requirements:

• Behaviour: New container instances are started alongside the old ones; health checks verify readiness; traffic is gradually shifted to new containers; old containers are stopped after successful rollout.
• Requirements:
  • Deployment strategy: docker (rolling updates not available for pm2 or native deployments)
  • Server resources: recommended ≥2GB RAM to run multiple containers concurrently
  • Project build artifacts (images) must be buildable on the host or available in a registry

Troubleshooting & notes

• Ensure SkyPort is reachable from GitHub (public URL or tunnel) and that the webhook URL uses HTTPS for GitHub.
• Check SkyPort logs and the deployment log file (recorded with each deployment) for build and rollout output.
• If you prefer not to expose secrets in the UI, only copy the secret at creation time and store it in a secure vault.

Next: Authentication