Webhooks and event integration

Hubfly space has two webhook directions. Registry webhooks send an event from Hubfly space to your service. Deployment webhooks receive a request from your CI system and start a deployment. Configure them separately because they use different URLs, credentials, and signature headers.

Choose a webhook type

Need	Use	Documentation
Notify Slack, an incident service, or your backend after an image event	Registry webhook	This page
Redeploy a container after CI publishes an image or builds from Git	Deployment webhook	Deployment pipelines

Registry webhooks

Open Project → Registry → Webhooks and choose Create webhook. Enter a label, the HTTPS receiver URL, an optional signing secret, and the events to deliver. The webhook is active after creation.

Event	When it is sent
`image.pushed`	An image is successfully pushed to the project registry.
`image.deleted`	An image is deleted from the project registry.
`image.moved`	An image reference or tag is moved.
`image.copied`	An image is copied to another reference.
`image.scan.completed`	An image vulnerability scan finishes.
`*`	All supported registry events. Use this only when the receiver can safely handle new event types.

Every delivery is a JSON document with this envelope:

json

{
  "event": "image.pushed",
  "deliveryId": "delivery_123",
  "webhookId": "webhook_456",
  "payload": {
    "image": "hubcell.local/acme/api",
    "tag": "v2.4.0"
  },
  "timestamp": "2026-08-19T12:34:56.000Z"
}

The payload object contains event-specific data. Use the top-levelevent to choose how to process it and deliveryId to make your handler idempotent.

Verify registry deliveries

If you configure a secret, Hubfly space signs the exact UTF-8 JSON body with HMAC-SHA256 and sends:

text

Content-Type: application/json
X-Hubfly-Event: image.pushed
X-Hubfly-Delivery: delivery_123
X-Hubfly-Signature: sha256=<64 hexadecimal characters>

Verify the raw body

Read the request body as raw bytes before parsing JSON. Re-serializing the parsed object can change whitespace or property order and will produce a different signature. Compare signatures in constant time and keep the secret only in your server's secret store.

javascript

import crypto from "node:crypto";

function verifyHubFlyDelivery(rawBody, secret, timestamp, received) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "utf8");
  const receivedBuffer = Buffer.from(received ?? "", "utf8");
  return expectedBuffer.length === receivedBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

Delivery history

The Registry → Webhooks view keeps the latest delivery records for each webhook. A record includes the event, delivery ID, status, response code and body when available, error details, and created/completed timestamps. Use the history to confirm that your receiver returned a successful response and to diagnose endpoint or signature failures.

Return quickly

Return a 2xx response after accepting the event, then process long-running work in a queue. Hubfly space records one delivery attempt; automatic retry scheduling is not exposed as part of the current registry webhook contract. If an event is important, make the receiver idempotent and replay it from your own event log or trigger the underlying registry action again.

Manage registry webhooks with the API

Use a Hubfly space personal access token with the project permission required by the endpoint. These are registry notification webhooks, not deployment triggers:

POST /api/v1/projects/:projectId/registry/webhooks/create — create one
GET /api/v1/projects/:projectId/registry/webhooks — list them
PUT /api/v1/projects/:projectId/registry/webhooks/:webhookId/update — update label, URL, secret, or events
DELETE /api/v1/projects/:projectId/registry/webhooks/:webhookId/delete — remove one
GET /api/v1/projects/:projectId/registry/webhooks/:webhookId/deliveries — inspect delivery history

The secret is not returned after creation. Store it when the create response provides it, or replace the webhook if it is lost. For incoming CI triggers, use thedeployment pipeline webhook guide.