Webhook Setup

BlameTrail receives deploy events through a simple HTTP webhook. You add a step to your CI/CD pipeline that fires a POST request after each successful deployment. BlameTrail records the event, links it to the correct service, and queues it for enrichment and suspect scoring.

Endpoint

POST /api/ingest/deploy

Authentication

Every deploy webhook request must include the service's deploy token in the X-Deploy-Token header:

X-Deploy-Token: dpl_a1b2c3d4e5f6...

Each token is scoped to a single service and tenant. The token is generated when you create a service and is shown once. Store it securely in your CI/CD system's secrets manager.

Request body

Send a JSON payload with the following fields:

Each object in the commits array can include:

CI/CD examples

GitHub Actions

- name: Notify BlameTrail
  if: success()
  run: |
    curl -s -X POST "${{ secrets.BLAMETRAIL_URL }}/api/ingest/deploy" \
      -H "Content-Type: application/json" \
      -H "X-Deploy-Token: ${{ secrets.BLAMETRAIL_DEPLOY_TOKEN }}" \
      -d '{
        "commit_sha": "${{ github.sha }}",
        "commit_message": "${{ github.event.head_commit.message }}",
        "branch": "${{ github.ref_name }}",
        "deployed_by": "${{ github.actor }}",
        "environment": "production",
        "url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
      }'

Store BLAMETRAIL_URL and BLAMETRAIL_DEPLOY_TOKEN as repository secrets under Settings > Secrets and variables > Actions in GitHub.

GitLab CI

notify_blametrail:
  stage: deploy
  script:
    - |
      curl -s -X POST "${BLAMETRAIL_URL}/api/ingest/deploy" \
        -H "Content-Type: application/json" \
        -H "X-Deploy-Token: ${BLAMETRAIL_DEPLOY_TOKEN}" \
        -d "{
          \"commit_sha\": \"${CI_COMMIT_SHA}\",
          \"commit_message\": \"${CI_COMMIT_MESSAGE}\",
          \"branch\": \"${CI_COMMIT_REF_NAME}\",
          \"deployed_by\": \"${GITLAB_USER_LOGIN}\",
          \"environment\": \"production\",
          \"url\": \"${CI_PIPELINE_URL}\"
        }"
  when: on_success

Add BLAMETRAIL_URL and BLAMETRAIL_DEPLOY_TOKEN as CI/CD variables in Settings > CI/CD > Variables in GitLab.

Plain curl

curl -X POST "https://blametrail.com/api/ingest/deploy" \
  -H "Content-Type: application/json" \
  -H "X-Deploy-Token: dpl_a1b2c3d4e5f6..." \
  -d '{
    "commit_sha": "abc123def456",
    "commit_message": "Fix payment timeout handling",
    "branch": "main",
    "deployed_by": "jane",
    "environment": "production",
    "version": "v2.4.1"
  }'

Response

A successful request returns:

{
  "status": "ok",
  "deploy_id": "uuid-of-the-deploy"
}

If you include an X-Idempotency-Key header and the same key has already been processed for that token, you receive:

{
  "status": "duplicate"
}

Idempotency

To prevent duplicate deploy records from retries, include an X-Idempotency-Key header with a unique value per deploy (e.g., the CI run ID). Duplicate requests with the same key and token pair return a 200 with "status": "duplicate" instead of creating a new record.

Token rotation

If a deploy token is compromised, rotate it immediately:

1. Open the service detail page in BlameTrail.
2. Click Rotate Token in the deploy webhook section.
3. Copy the new token and update your CI/CD secrets.

The previous token is invalidated immediately. Any in-flight requests using the old token will be rejected.

Limits

• Request body size: 100 KB maximum. Requests exceeding this limit are rejected with a 413 status code.
• Rate limit: 60 requests per minute per IP address.
• Commits array: Maximum 100 items.