Webhooks

Receive events from your tools via webhook endpoints.

Table of contents

1. Overview
2. Authentication
3. Webhook Endpoints
   1. Perforce
   2. Jenkins
   3. Game Engine
   4. Deployment
   5. CI Systems
      1. Non-Jenkins CI must push its log
   6. Other Integrations
4. Response Codes
5. Testing Webhooks

Overview

Webhooks allow external tools to send events to ButterStack. Each integration has its own webhook endpoint with a unique token for authentication.

Authentication

All webhook endpoints use token-based authentication. The webhook_token is generated when you create an integration and is shown on the integration’s page (Project → Integrations → your integration).

The token can be delivered three ways; prefer a header, since a query string lands in proxy and access logs:

POST /webhooks/{platform}?token={webhook_token}

Webhook Endpoints

Perforce

Endpoint: POST /webhooks/perforce

Jenkins

Endpoint: POST /webhooks/jenkins

Body (JSON):

{
  "job_name": "MyGame-Build",
  "build_number": 456,
  "status": "SUCCESS",
  "build_url": "https://jenkins.example.com/job/MyGame-Build/456"
}

Game Engine

Deployment

Endpoint: POST /webhooks/deployment

Body:

{
  "platform": "steam",
  "event": "uploaded",
  "build_number": 456,
  "steam_app_id": "480"
}

Platform values: steam (alias steamworks), reddit_devvit (aliases reddit, devvit), youtube_playables (aliases youtube, playables), epic_games_store (aliases epic, epic_games), google_play (aliases google, android), apple_app_store (aliases apple, ios, app_store), unity_cloud (alias unity). Any other value is recorded as custom.

CI Systems

Non-Jenkins CI must push its log

ButterStack polls the Jenkins API for console output, artifacts, and build info. No other CI provider is polled - a CI server inside a studio’s own network is not reachable from ButterStack, and a build_url pointing at an internal host (http://teamcity-server:8111/...) or a private-tailnet address resolves to nothing from the outside.

So for GitHub Actions, TeamCity, or any other non-Jenkins poster, the log has to ride on the webhook payload itself:

{
  "job_name": "PilotLight_Verify",
  "build_number": "298",
  "status": "FAILURE",
  "build_url": "https://teamcity.example.com/buildConfiguration/PilotLight_Verify/298",
  "changelist": "207",
  "logs_tail": "<the last few hundred KB of the build log>"
}

logs_tail (also accepted as log or console) populates output_log, capped at 256,000 characters with the oldest content dropped first. A report that omits it leaves ButterStack with no log for that build.

This is not cosmetic: output_log is the only build output the AI failure investigator can read. Without logs_tail the investigator has no error text to work from and will return a low-confidence infrastructure finding saying so rather than a real diagnosis (#1940).

Other Integrations

Each of these except the CI intake also answers GET /webhooks/{platform}/verify, which returns {"status":"verified","service":"..."} for provider handshakes.

Response Codes

There is no {project_id} path segment on any webhook endpoint: the token identifies the integration, and therefore the project.

Testing Webhooks

curl -X POST \
  "https://www.butterstack.com/webhooks/perforce" \
  -H "X-ButterStack-Token: YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "changelist=12345"