Integrations Reference

Generated from the original Cascades integrations reference on 2026-04-07.

Below the matrix are implementation recipes—“how do I connect X?”—with patterns that compose with REST endpoints and webhooks. For Stripe billing + CLI, see Stripe (CLI workflow).

How to wire a provider end-to-end

1. POST the provider-specific connect route with OAuth/API tokens your policy allows.
2. POST the test route to validate credentials (200 proves round-trip—not just parsing).
3. Register outbound webhooks at the vendor using the Cascades webhook URL surfaced in dashboards or API responses. Each vendor signs payloads differently—prefer per-integration signing secrets.
4. Bind the webhook to the Default Workflow slug from the matrix so ingestion becomes a structured run—not a dangling script invocation.

GitHub workflows

Typical linkage for change-aware automation:

POST https://<{your-cascades-host}>/api/integrations/github/connect
Authorization: Bearer <operator-token>
Content-Type: application/json

{"installationId": "...","enterpriseSlug": "...","fineGrainedScopes": ["repo"]}

• Register repository webhooks targeting /api/integrations/github/webhook — verify signatures GitHub attaches (X-Hub-Signature-256).
• Map events (pull_request, workflow_run) to wf-change-control-proof catalogue rows unless you authored a narrower graph.

GitLab pipelines

Analogous handshake:

POST https://<{your-cascades-host}>/api/integrations/gitlab/connect
Authorization: Bearer <operator-token>

{"token": "<gitlab-pat-or-oauth>","baseUrl": "https://gitlab.com/api/v4"}

• Project hooks should point to /api/integrations/gitlab/webhook.
• For merge-to-main attestations keep branch filters explicit so unintended tag pushes cannot trigger guarded workflows.

Slack notifications & slash-friendly flows

Connecting Slack installs the OAuth app Cascades publishes per deployment:

POST /api/integrations/slack/connect
{"teamId":"T……","incomingWebhook":"","botToken":"<xoxb-*>","signingSecret":"***"}

• Route approval / escalation workflows through Slack using task outputs as templated payloads; never embed tenant secrets verbatim in ephemeral messages—reference masked links back to Cascades dashboards instead.

REST composition for orchestration-heavy teams

Prefer thin glue controllers that orchestrate Cascades—not duplicating graphs:

POST https://<{your-cascades-host}>/api/workflow/run
Authorization: Bearer <service token>
Content-Type: application/json

{"workflowSlug":"wf-support-escalation-proof","context":{"ticketId":"INC-1024"},"idempotencyKey":"support-INC-1024-20260427"}

Reuse API quickstart headers for traceability.

Webhooks egress & retries

Operational systems should implement bounded retries, idempotency keys, DLQ dashboards mirrored to Cascades proofs when applicable—consult third-party Systems vendor-specific quirks.

External SaaS wrappers

Anything reachable over HTTPS belongs behind typed task adapters (workflow builder) so retries/timeouts stay uniform.

Provider matrix

Notes

• Use POST /api/integrations/seed-demo to create demo-ready integration configs.
• Use GET /api/integrations to list configured integrations.
• Use GET /api/integrations/catalog for provider metadata and connection stats.
• In v2, the dashboard integrations surface is available at /dashboard/integrations.