Skip to main content

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.

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

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 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.
If you’re using the ecr-mirror-lambda reference implementation, signature verification is handled for you automatically.

​
Event Types

Event typeWhen it fires
io.root.cr.image.created.v1A 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). 
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:
FieldDescription
idDelivery attempt ID
subscription_idThe webhook subscription that was tested
event_idID of the event that was sent
statuspending, delivered, or failed
http_statusHTTP status code returned by your endpoint
sent_atTimestamp of the delivery attempt
error_reasonHuman-readable error message if delivery failed
typeEvent 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 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.

ecr-mirror-lambda

Deploy a pre-built Lambda that mirrors Root remediated images to your ECR automatically.
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 to get started.