Skip to main content
Stout uses webhooks in two distinct directions. Depending on what you’re trying to wire up, you probably want one of:
  • Inbound webhooks — your Git provider (GitHub or GitLab) notifies Stout when something happens in a repo, so a workflow can trigger.
  • Alert webhooks — Stout POSTs JSON to a URL you configure whenever an alert fires on one of your boxes.

​
Inbound webhooks (GitHub / GitLab)

Workflows can be triggered by GitHub or GitLab events — a push to a branch, a pull request opened, etc. To wire this up, Stout registers a webhook endpoint with the provider; the provider POSTs events there; Stout verifies the signature and runs any matching workflow triggers.

​
Configuring an inbound webhook

From Settings → Integrations → Webhooks → New:
  1. Provider — github or gitlab. (No other providers are supported today.)
  2. URL — the callback URL Stout displays; paste this into your provider’s webhook configuration.
  3. Secret — a shared secret. For GitHub, Stout verifies the x-hub-signature-256 header (HMAC-SHA256 of the raw body). For GitLab, Stout verifies the x-gitlab-token header matches the secret.
Once configured, each incoming event is logged under the webhook’s event history so you can see whether Stout received, matched, and dispatched it.

​
What triggers a workflow

Configure a workflow’s triggers (see the Workflows page) to listen for push or pull_request events from a given repo. When a matching inbound webhook arrives, Stout creates a workflow run.

​
Alert webhooks (outbound)

When an alert fires — a box goes unhealthy, heartbeats stop, error rates spike, or a resource hits a threshold — Stout can POST a JSON payload to an external URL. Use this to bridge alerts into Slack (via an incoming webhook), PagerDuty, or your own dashboard.

​
Configuring an alert webhook

From Settings → Integrations:
  1. URL — the HTTPS endpoint Stout will POST to.
  2. Custom headers — optional key/value pairs, e.g. Authorization: Bearer <token> for protected endpoints.
  3. Secret — optional shared secret used to sign the request body.
Each alert webhook is scoped to one organization and receives all alerts for that org. Per-alert-type routing isn’t exposed in the UI yet — if you need to split alerts across destinations, configure multiple webhooks and filter at your end.

​
What fires

Alerts today include: health_low, heartbeat_lost, error_spike, and resource_high. See the Organizations page for how alerts are surfaced in the dashboard.

​
Coming soon

A general-purpose outbound webhook system — firing on arbitrary events (job completion, workflow run finished, factory run finished, and so on), with a richer event catalog, signed X-Stout-Signature headers, and UI-surfaced retry history — is in planning. Until that ships, use alert webhooks for alerts and poll the HTTP API for job/workflow/run state.