> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/registries/webhooks/webhook-payload-reference.md).

# Webhook payload reference

Structure and fields of the HTTP POST payload Harness sends to your webhook endpoint when an artifact event fires, including signature verification.

When a webhook fires, Harness sends an HTTP POST request to the configured payload URL. The request body is a JSON object describing the event, the artifact involved, and the registry context.

## Request headers

Every webhook delivery includes the following HTTP headers:

| Header                | Value                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`        | `application/json`                                                                                                                                                    |
| `X-Harness-Event`     | The event type: `artifact.created` or `artifact.deleted`                                                                                                              |
| `X-Harness-Delivery`  | A unique UUID for this delivery attempt                                                                                                                               |
| `X-Hub-Signature-256` | Hash-based Message Authentication Code (HMAC)-SHA256 signature of the payload body, prefixed with `sha256=`. Present only when a secret is configured on the webhook. |

Any custom headers you added when creating the webhook are also included.

## Signature verification

When you configure a webhook secret, Harness signs the raw request body using HMAC-SHA256 with your secret as the key. The signature is sent in the `X-Hub-Signature-256` header.

To verify the signature on your server:

1. Compute `HMAC-SHA256(secret, raw_request_body)`.
2. Compare the result (hex-encoded, prefixed with `sha256=`) to the value in `X-Hub-Signature-256`.
3. Reject the request if the values do not match.

Use a constant-time string comparison to prevent timing attacks.

## Payload structure

```json
{
  "event": "artifact.created",
  "deliveryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-11-06T10:30:00Z",
  "account": {
    "id": "<account_id>"
  },
  "org": {
    "id": "<org_id>"
  },
  "project": {
    "id": "<project_id>"
  },
  "registry": {
    "name": "my-docker-registry",
    "type": "DOCKER"
  },
  "artifact": {
    "name": "my-service",
    "version": "1.25.2",
    "digest": "sha256:620e85a7b3b4e8da94b3adb1c23df58c04a6e5e7e9e1a2b3c4d5e6f7a8b9c0d1",
    "size": 52428800,
    "format": "DOCKER",
    "labels": {},
    "metadata": {}
  },
  "trigger": {
    "type": "push",
    "actor": "user@example.com"
  }
}
```

## Field reference

### Top-level fields

| Field        | Type   | Description                                                                           |
| ------------ | ------ | ------------------------------------------------------------------------------------- |
| `event`      | string | The event type. One of: `artifact.created`, `artifact.deleted`.                       |
| `deliveryId` | string | A UUID that uniquely identifies this delivery attempt. Use it to deduplicate retries. |
| `timestamp`  | string | ISO 8601 UTC timestamp of when the event was generated.                               |

### `account`, `org`, `project`

| Field | Type   | Description                                                                                      |
| ----- | ------ | ------------------------------------------------------------------------------------------------ |
| `id`  | string | The Harness identifier for the account, organization, or project scope where the registry lives. |

### `registry`

| Field  | Type   | Description                                                                                  |
| ------ | ------ | -------------------------------------------------------------------------------------------- |
| `name` | string | The registry name as shown in the Harness UI.                                                |
| `type` | string | The registry format in uppercase: `DOCKER`, `MAVEN`, `NPM`, `PYTHON`, `HELM_OCI`, and so on. |

### `artifact`

| Field      | Type    | Description                                                                                                                                                                         |
| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string  | The artifact name within the registry.                                                                                                                                              |
| `version`  | string  | The version identifier: a tag for most formats, or a digest for Docker and OCI images when the version has no tag.                                                                  |
| `digest`   | string  | The content-addressable digest of the artifact. For Docker and OCI images, this is the manifest digest (`sha256:…`). For other formats, this is a checksum of the artifact content. |
| `size`     | integer | The size of the artifact in bytes.                                                                                                                                                  |
| `format`   | string  | The artifact format. Matches `registry.type`.                                                                                                                                       |
| `labels`   | object  | Key-value labels attached to the artifact, if any.                                                                                                                                  |
| `metadata` | object  | Custom metadata key-value pairs attached to the artifact version, if any.                                                                                                           |

### `trigger`

| Field   | Type   | Description                                                                                                                                                                        |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`  | string | How the event was produced. `push` for a direct client push; `upstream_cache` for an artifact fetched through an upstream proxy; `delete` for a manual or lifecycle-rule deletion. |
| `actor` | string | The email address or service account identifier of the user or automation that triggered the event.                                                                                |

## Artifact Creation payload example

```json
{
  "event": "artifact.created",
  "deliveryId": "f7e6d5c4-b3a2-1098-fedc-ba9876543210",
  "timestamp": "2026-11-06T14:22:31Z",
  "account": { "id": "lXyZ1234" },
  "org": { "id": "my-org" },
  "project": { "id": "platform-team" },
  "registry": {
    "name": "backend-images",
    "type": "DOCKER"
  },
  "artifact": {
    "name": "api-service",
    "version": "2.3.0",
    "digest": "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abc123",
    "size": 73400320,
    "format": "DOCKER",
    "labels": { "team": "platform" },
    "metadata": { "build_id": "ci-1042" }
  },
  "trigger": {
    "type": "push",
    "actor": "ci-bot@example.com"
  }
}
```

## Artifact Deletion payload example

```json
{
  "event": "artifact.deleted",
  "deliveryId": "11223344-5566-7788-99aa-bbccddeeff00",
  "timestamp": "2026-11-06T16:05:10Z",
  "account": { "id": "lXyZ1234" },
  "org": { "id": "my-org" },
  "project": { "id": "platform-team" },
  "registry": {
    "name": "backend-images",
    "type": "DOCKER"
  },
  "artifact": {
    "name": "api-service",
    "version": "1.8.0",
    "digest": "sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "size": 68157440,
    "format": "DOCKER",
    "labels": {},
    "metadata": {}
  },
  "trigger": {
    "type": "delete",
    "actor": "jane.doe@example.com"
  }
}
```

## Delivery retries

Harness retries failed webhook deliveries when your endpoint returns a non-2xx HTTP status or does not respond within the timeout. Retries use an exponential backoff schedule. Use the `deliveryId` field to identify and deduplicate retried deliveries on your endpoint.

## Next steps

* [Create a webhook](https://developer.harness.io/artifact-registry/3.0/registries/webhooks/create-a-webhook.md)
* [Webhooks overview](https://developer.harness.io/artifact-registry/3.0/registries/webhooks.md)

{% @harness-feedback/feedback %}
