Metadata

Docs

Metadata

Attach custom data to snapshot jobs for correlation, tagging, and integration.

The metadata field accepts arbitrary key-value data that is echoed back in job payloads. Use it to correlate snapshots with your systems, tag jobs for organization, or pass context to webhook handlers.

Schema

Field	Type	Required	Notes
`metadata`	`Record<string, unknown>`	No	Any valid JSON object. Nested structures are supported.

How It Works

You include a metadata object in your snapshot request
The metadata is stored with the job and returned in all status responses
Webhook payloads include the metadata, allowing your handlers to identify the source request

Example Request

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://site.com/"
    ],
    "viewports": [
      { "width": 1280, "height": 800 }
    ],
    "metadata": {
      "requestId": "req_abc123",
      "project": "marketing-site",
      "environment": "production",
      "triggeredBy": "ci-pipeline"
    }
  }' \
  "https://api.watchero.io/api/v1/snapshots"

Response with Metadata

When you retrieve the snapshot status, metadata is included:

{
  "id": "cmhdgfak60002mdtxnen6g2qi",
  "status": "COMPLETE",
  "metadata": {
    "requestId": "req_abc123",
    "project": "marketing-site",
    "environment": "production",
    "triggeredBy": "ci-pipeline"
  },
  "results": [...]
}

Common Use Cases

Correlation IDs

Link snapshots back to your internal systems:

{
  "metadata": {
    "requestId": "req_abc123",
    "userId": "user_456",
    "sessionId": "sess_789"
  }
}

This allows you to:

Match webhook callbacks to original requests
Debug issues by tracing through your logs
Associate snapshots with user actions

Project Tagging

Organize snapshots by project, team, or purpose:

{
  "metadata": {
    "project": "marketing-site",
    "team": "design",
    "sprint": "2024-Q1-W3",
    "ticket": "DESIGN-1234"
  }
}

Environment Context

Track which environment a snapshot came from:

{
  "metadata": {
    "environment": "staging",
    "branch": "feature/new-homepage",
    "commit": "a1b2c3d4",
    "buildNumber": 1234
  }
}

CI/CD Integration

Pass build context for automated visual regression testing:

{
  "metadata": {
    "ci": {
      "provider": "github-actions",
      "runId": "12345678",
      "workflow": "visual-tests",
      "actor": "dependabot[bot]"
    },
    "pullRequest": {
      "number": 42,
      "branch": "update-dependencies"
    }
  }
}

Webhook Processing

When using webhooks, metadata helps route and process callbacks:

{
  "metadata": {
    "callbackContext": {
      "action": "compare-with-baseline",
      "baselineId": "snap_baseline_001",
      "notifyChannel": "#design-review"
    }
  }
}

Your webhook handler receives this metadata and can:

Trigger comparison workflows
Post results to Slack channels
Update issue trackers
Store results in your database with proper associations

Best Practices

Keep It Relevant

Include only data you'll actually use. Avoid dumping entire request contexts:

// ✅ Good - focused, useful data
{
  "metadata": {
    "requestId": "req_123",
    "project": "homepage"
  }
}
 
// ❌ Avoid - unnecessary bulk
{
  "metadata": {
    "entireRequestObject": { ... },
    "serverTimestamp": "...",
    "unusedField": "..."
  }
}

Use Consistent Keys

Standardize your metadata schema across requests for easier querying:

// Always use the same structure
{
  "metadata": {
    "project": "string",
    "environment": "production|staging|development",
    "requestId": "string"
  }
}

Avoid Sensitive Data

Do not include sensitive information like API keys, passwords, or PII in metadata. While metadata is stored securely, it appears in API responses and webhook payloads.

Size Limits

Metadata is limited to 64 KB when serialized as JSON. For most use cases, this is more than sufficient. If you need to associate large amounts of data with a snapshot, store it in your own system and include only a reference ID in metadata.

Credentials Get Snapshot