Back To Core Concepts

Cartos Release Trigger: Setup & Requirements

Use this when you want CI/CD (GitHub Actions, GitLab, CircleCI, etc.) to notify Cartos about a release so Cartos can start ownership and impact follow-up.

If you need help with where to configure the company-level token in the product, start with Company Settings: Configure Cartos, Integrations, and Webhooks.

Endpoint

  • POST /api/public/cartos-release-trigger

Example full URL:

  • https://your-anamap-domain.com/api/public/cartos-release-trigger

Legacy endpoint support remains available during the transition:

  • https://your-anamap-domain.com/api/public/cartos-release-webhook

Authentication (required in production)

Cartos validates one of the following token sources:

  1. Company-level release token (configured in Company Settings)
  2. Environment fallback token (AGENT_RELEASE_WEBHOOK_TOKEN or AGENT_EMAIL_WEBHOOK_TOKEN)

Send the token in one of these locations:

  • Header: x-cartos-release-trigger-token: <token> (recommended)
  • Header: x-cartos-webhook-token: <token> (legacy)
  • Header: Authorization: Bearer <token>
  • Header: x-webhook-token: <token>
  • Query string: ?token=<token>

Where to manage the token in Anamap

If you want a company-specific webhook credential instead of relying only on an environment fallback token:

  1. Open the Company Dashboard for the correct company.
  2. Open Company Settings.
  3. Find the Cartos Release Trigger section.
  4. Paste a new token into Release Webhook Token (set or rotate).
  5. Save the token.

You can also disable the company-level token from that same settings block.

Minimum payload required

  • companyId (UUID) is required

Recommended payload:

{
  "provider": "github-actions",
  "companyId": "<company-uuid>",
  "eventType": "release",
  "eventId": "release-2026-03-01-001",
  "releaseName": "Checkout Funnel Update",
  "description": "Improved checkout UX and instrumentation updates.",
  "tags": ["checkout", "funnel"],
  "changeType": "new_feature",
  "version": "v2.4.0",
  "environment": "prod"
}

Success and duplicate behavior

  • 202: accepted, Cartos created follow-up question and queued processing
  • 401: token invalid/missing
  • 409: duplicate webhook event (same provider + webhook ID)

Local verification

You can validate end-to-end with:

  • npm run -s test:agent-release-webhook -- --replay --company-id <uuid> --token <token>

Optional flags:

  • --url <webhook-url>
  • --type release|pr|deployment
  • --event-id <stable-id>

What Cartos does after receipt

  • Creates a high-priority ownership/impact question
  • Sets urgency window from connected sources:
    • Amplitude connected: 1 hour
    • Otherwise: 24 hours
  • Attempts immediate worker run if AGENT_WORKER_BASE_URL is configured

For the broader operating model around recipients, follow-up, and channel behavior, see How Cartos Operates: What to Expect as a Team and Interacting with Cartos: Chat, Email, Slack, and Better Context.