Deployment pipelines

A deployment pipeline webhook is an incoming HTTP endpoint for a Hubfly space project. Your CI provider calls it after a build or image publication, and Hubfly space performs the selected action for one container or for the container named in the request.

How deployment webhooks work

1. Create a webhook in the project Dashboard and select its target and allowed actions.
2. Copy the generated URL and, for Secure mode, the signing secret. The secret is shown only once.
3. Store those values in your CI provider's encrypted secrets.
4. Send a JSON request after the image or Git source is ready.
5. Open the project's Deployments view to inspect the resulting event and any error.

Create a webhook

In the Dashboard, open Project → Deployments → Pipeline Console and chooseRegister Webhook. Configure these fields:

Choose an authentication mode

Call the endpoint

Use the exact generated URL from the Dashboard. Its path has one of these shapes:

# Basic or Standard mode (the generated URL includes TOKEN)
POST https://api.hubfly.space/api/webhooks/deploy/WEBHOOK_ID/TOKEN

# Secure mode (the generated URL has no token)
POST https://api.hubfly.space/api/webhooks/deploy/WEBHOOK_ID

Basic and Standard requests authenticate with the token in the URL path. Secure requests must include both headers below. The signature is calculated over TIMESTAMP.rawBody, including the dot, and the timestamp must be within five minutes of Hubfly space's clock.

X-Hub-Timestamp: 1710000000
X-Hub-Signature-256: sha256=<64 hexadecimal characters>

Request payloads

JSON field names are case-sensitive. An empty body defaults to a pull action. A project-scoped webhook must include containerId; a webhook already attached to a container does not need it.

Pull an image or Git source

{
  "action": "pull",
  "containerId": "container_123",
  "image": "ghcr.io/acme/api:v2.4.0"
}

For a Git-backed container, use ref (or branch) and optionallycommitSha (or commit) instead of image:

{
  "action": "pull",
  "ref": "main",
  "commitSha": "7f3b1a9"
}

Update runtime configuration

The update action can include a new image and supported container settings. The example uses the top-level aliases accepted by the webhook parser; nestedcontainer, spec, and update objects are also accepted.

{
  "action": "update",
  "image": "ghcr.io/acme/api:v2.4.0",
  "environment": {
    "APP_ENV": "production",
    "LOG_LEVEL": "info"
  },
  "restartPolicy": "unless-stopped"
}

Restart or roll back

{ "action": "restart" }

{ "action": "rollback" }

Rollback is an explicit action. If you configure rollback options for an update, you can also send rollback.enabled, rollback.onHealthCheckFail, and a positiverollback.timeoutSeconds. Inspect the deployment event to confirm whether the requested action succeeded; rollback is not a guarantee that every failed deployment has a previous version available.

GitHub Actions example

Add HUBFLY_WEBHOOK_URL and, for Secure mode, HUBFLY_WEBHOOK_SECRET as GitHub Actions secrets. This workflow signs the exact body sent with curl:

name: Deploy to Hubfly space
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Hubfly space deployment
        env:
          HUBFLY_WEBHOOK_URL: ${{ secrets.HUBFLY_WEBHOOK_URL }}
          HUBFLY_WEBHOOK_SECRET: ${{ secrets.HUBFLY_WEBHOOK_SECRET }}
          COMMIT_SHA: ${{ github.sha }}
        run: |
          body=$(printf '{"action":"pull","ref":"main","commitSha":"%s"}' "$COMMIT_SHA")
          timestamp=$(date +%s)
          signature=$(printf '%s.%s' "$timestamp" "$body" |             openssl dgst -sha256 -hmac "$HUBFLY_WEBHOOK_SECRET" -hex | sed 's/^.* //')

          curl --fail-with-body -X POST "$HUBFLY_WEBHOOK_URL"             -H 'Content-Type: application/json'             -H "X-Hub-Timestamp: $timestamp"             -H "X-Hub-Signature-256: sha256=$signature"             --data "$body"

Monitor and troubleshoot

View the project's Deployments or Pipeline Console to see the action, trigger, status, duration, target container, and error details for each deployment event. The API can list the same project deployment history with GET /api/v1/projects/:projectId/deployments.

For registry event notifications, use Registry webhooks. For endpoint schemas and response examples, see the API reference.