> ## Documentation Index
> Fetch the complete documentation index at: https://docs.root.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Get notified when Root creates a new remediated image tag - via webhook or Slack.

When Root remediates a container image and creates a new Root Remediated Tag (RRT), it can notify you - via a webhook to an HTTPS endpoint you control, or via a Slack message to your workspace.

## Use Cases

* **Auto-mirror to a private registry** - copy new remediated images to Amazon ECR, JFrog Artifactory, or any other registry as soon as Root publishes them
* **Trigger CI/CD pipelines** - kick off a rebuild or redeploy whenever a base image is patched
* **Audit and logging** - record remediation events in your own systems

## How It Works

1. You register a webhook endpoint URL with Root and specify which event types to subscribe to
2. When a new RRT is created, Root sends a signed HTTP `POST` to your endpoint
3. Your endpoint verifies the signature and processes the event

## Setting Up a Webhook

Webhook subscriptions are managed via the Root API. UI support is coming soon.

### Step 1 - Register your endpoint

```sh theme={null}
curl -X POST https://api.root.io/v3/settings/webhooks \
  -u "<your-token>:" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-endpoint.example.com/",
    "description": "Mirror to ECR",
    "event_types": ["io.root.cr.image.created.v1"]
  }'
```

The response body includes a `secret` field - this is your **webhook signing secret**. Copy it now; Root uses it to sign every request so your endpoint can verify it came from Root.

### Step 2 - Verify webhook signatures

Every webhook Root sends is signed with HMAC-SHA256 following the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Your endpoint should verify the signature on every incoming request before acting on it.

The signature is included in the `webhook-signature` header. Requests with timestamps older than 5 minutes should be rejected to prevent replay attacks.

<Note>
  If you're using the [ecr-mirror-lambda](#example-auto-mirror-to-amazon-ecr) reference implementation, signature verification is handled for you automatically.
</Note>

## Event Types

| Event type                    | When it fires                              |
| ----------------------------- | ------------------------------------------ |
| `io.root.cr.image.created.v1` | A new Root Remediated Tag has been created |

## Testing a Webhook

Before relying on your endpoint in production, you can trigger a test delivery against any existing webhook subscription using a real Root Remediated Tag (RRT).

```sh theme={null}
curl -X POST https://api.root.io/v3/settings/webhooks/<webhookSubscriptionID>/test-tag-created \
  -u "<your-token>:" \
  -H "Content-Type: application/json" \
  -d '{
    "root_registry_tag_id": "<rrt-id>"
  }'
```

Root will send a real signed `POST` to your endpoint using the specified RRT and return the delivery result:

| Field             | Description                                     |
| ----------------- | ----------------------------------------------- |
| `id`              | Delivery attempt ID                             |
| `subscription_id` | The webhook subscription that was tested        |
| `event_id`        | ID of the event that was sent                   |
| `status`          | `pending`, `delivered`, or `failed`             |
| `http_status`     | HTTP status code returned by your endpoint      |
| `sent_at`         | Timestamp of the delivery attempt               |
| `error_reason`    | Human-readable error message if delivery failed |
| `type`            | Event type that was delivered                   |

**Error responses:**

* `404` — The subscription ID or RRT ID was not found
* `422` — The subscription does not subscribe to the `io.root.cr.image.created.v1` event type

## Example: Auto-Mirror to Amazon ECR

[ecr-mirror-lambda](https://github.com/rootio-avr/ecr-mirror-lambda) is a ready-to-deploy AWS Lambda that receives Root webhooks and automatically copies each new remediated image into your ECR. Deploy it once with Terraform and every new RRT will appear in your ECR without any manual steps.

<Card title="ecr-mirror-lambda" icon="github" href="https://github.com/rootio-avr/ecr-mirror-lambda">
  Deploy a pre-built Lambda that mirrors Root remediated images to your ECR automatically.
</Card>

The Lambda supports an optional **repo allowlist**: set `allowed_repos` in `terraform.tfvars` (e.g. `["python", "golang"]`) to mirror only specific image repos. Events for unlisted repos are silently ignored. Omit the variable to mirror everything.

When an image arrives for an ECR repo that doesn't exist yet (e.g. `root-mirror/python`), the Lambda creates it automatically and copies the repository policy and lifecycle policy from the base repo (`root-mirror`).

## Slack Notifications

Root can send a Slack notification to your workspace when a new remediated image is available for your account. Each notification includes the image name and tag, so your team knows immediately when a patched version is ready to pull.

Slack notifications require a one-time setup by the Root team. [Contact us](https://www.root.io/contact) to get started.