Webhooks & Notifications

Relevant source files

The following files were used as context for generating this wiki page:

• src/jobservice/job/impl/notification/webhook_job.go
• api/v2.0/swagger.yaml
• src/portal/src/app/base/project/webhook/webhook.service.ts
• src/portal/src/app/base/project/webhook/webhook.component.ts
• src/portal/src/app/base/project/webhook/add-webhook-form/add-webhook-form.component.html
• src/jobservice/README.md

Webhooks and Notifications in Harbor serve as a mechanism to receive real-time callbacks at designated external endpoints when specific events occur within a project. This system enables integration with external CI/CD pipelines, messaging platforms like Slack, and custom management tools by sending event-driven payloads via HTTP POST requests.

The system is architected as an asynchronous background process. When a supported event—such as an image push, pull, or scan completion—is triggered, the notification system enqueues a WebhookJob in the Harbor Job Service. This job is responsible for dispatching the event metadata to the configured target address, handling retries, and providing execution logs for auditing purposes.

Sources: api/v2.0/swagger.yaml, src/jobservice/README.md, src/portal/src/app/base/project/webhook/webhook.service.ts

Webhook Architecture & Data Flow

The webhook system operates across the API layer, the portal UI, and the background Job Service. Users configure policies at the project level, which define the relationship between event types and notification targets.

Functional Flow

1. Event Trigger: A resource operation (e.g., PUSH_ARTIFACT) occurs.
2. Job Enqueueing: The notification controller identifies active policies for that project and enqueues a job in the Job Service.
3. Job Execution: A Job Service worker picks up the WebhookJob, initializes a client (handling TLS verification settings), and executes the HTTP POST request to the remote endpoint.
4. Logging: The success or failure of the delivery is recorded in the job's execution log.

The diagram above shows the lifecycle of a notification from the initial event to the final delivery to a remote endpoint.
Sources: src/jobservice/job/impl/notification/webhook_job.go:68-80, src/jobservice/README.md

Webhook Policies & Targets

A Webhook Policy defines which events should be sent to which endpoints. Each project can have multiple policies, though typically they are used to route different categories of events to different external systems.

Policy Configuration Components

• Targets: Objects containing the notification type (http or slack), target address, and optional authentication headers.
• Event Types: A list of specific triggers the policy listens for.
• Security Settings: Options to skip remote certificate verification (skip_cert_verify), useful for self-signed endpoints.
• Payload Formats: Supports Default and CloudEvents formats for interoperability.

Sources: api/v2.0/swagger.yaml: definitions/WebhookPolicy, src/portal/src/app/base/project/webhook/add-webhook-form/add-webhook-form.component.html:105-150

Supported Events

The system supports a wide range of events across the artifact lifecycle:

Event Identifier	Human-Readable Description
PUSH_ARTIFACT	Artifact pushed
PULL_ARTIFACT	Artifact pulled
DELETE_ARTIFACT	Artifact deleted
SCANNING_COMPLETED	Scanning finished
SCANNING_FAILED	Scanning failed
QUOTA_EXCEED	Project quota exceeded
REPLICATION	Replication status changed
TAG_RETENTION	Tag retention task finished

Sources: src/portal/src/app/base/project/webhook/webhook.service.ts:21-36

Notification Delivery (WebhookJob)

The WebhookJob is the concrete implementation of the delivery logic within the Harbor Job Service. It handles the low-level HTTP communication with the target endpoint.

Job Implementation Details

• Retries: By default, a webhook job is configured to allow up to 3 failed attempts before being marked as a final failure. This value can be overridden via the maxFails environment variable.
• Client Initialization: The job initializes an http.Client. If skip_cert_verify is set to true in the parameters, it uses an insecure client that does not validate the remote server's TLS certificate.
• Execution: The job performs an http.MethodPost to the configured address. It includes the payload string and any provided header strings (unmarshaled into http.Header).

Sources: src/jobservice/job/impl/notification/webhook_job.go:37-46, src/jobservice/job/impl/notification/webhook_job.go:83-96, src/jobservice/job/impl/notification/webhook_job.go:99-130

Error Handling

If the remote endpoint returns a status code outside the 2xx range, the job reads the response body, logs the error, and returns an error to the Job Service, which may trigger a retry based on the ShouldRetry status.

The sequence diagram illustrates the synchronous interaction between the Job Service worker and the remote endpoint during notification delivery.
Sources: src/jobservice/job/impl/notification/webhook_job.go:121-127

API Endpoints

Harbor provides a set of RESTful endpoints to manage project webhooks.

Method	Path	Description
GET	/projects/{project_name_or_id}/webhook/policies	List webhook policies for a project.
POST	/projects/{project_name_or_id}/webhook/policies	Create a new webhook policy.
PUT	/projects/{project_name_or_id}/webhook/policies/{id}	Update an existing policy (e.g., enable/disable).
DELETE	/projects/{project_name_or_id}/webhook/policies/{id}	Remove a webhook policy.
GET	/projects/{project_name_or_id}/webhook/events	Get supported event and notify types.
GET	/projects/{project_name_or_id}/webhook/policies/{id}/executions	View history of webhook deliveries.

Sources: api/v2.0/swagger.yaml: paths, src/portal/src/app/base/project/webhook/webhook.component.ts:205-240

Summary

Webhooks and Notifications provide project administrators with a flexible way to integrate Harbor into their DevOps ecosystem. By leveraging the Harbor Job Service, the system ensures that notifications are delivered reliably in the background without impacting the performance of the core registry operations. Users can monitor the status of these notifications through the portal's execution history, ensuring visibility into the success of external integrations.

Sources: src/jobservice/README.md, src/portal/src/app/base/project/webhook/webhook.component.ts