Webhooks and integrations

Stripe subscription webhook#

Endpoint:

POST /api/billing/webhook

The handler verifies the Stripe-Signature header with STRIPE_WEBHOOK_SECRET, then maps subscription created, updated, and deleted events into local plan and status fields. Invalid signatures return 400.

Configure the webhook in Stripe with the public API URL. Never expose the signing secret to the dashboard.

Chat webhook#

Endpoint:

POST /api/webhooks/chat/<org_id>

External callers sign the exact raw request body:

import hashlib
import hmac

body = b'{"text":"scrumpulse what is blocked?","user_name":"alex"}'
signature = hmac.new(
    b"<chat-webhook-signing-secret>",
    body,
    hashlib.sha256,
).hexdigest()

Send the hex digest in X-ScrumPulse-Signature. The server fails closed when CHAT_WEBHOOK_SIGNING_SECRET or the signature is missing. A matching Clerk organization identity is the alternate authenticated path.

The handler reads active board items and can use OpenAI plus optional Upstash Vector history. It returns generic text on internal failure and does not echo server exception details.

n8n replanner workflow#

integrations/n8n/scrumbot-replan-approval.workflow.json models a proposal webhook, Mattermost buttons, an approval webhook, and a safe Taiga approval comment.

It is an unvalidated import artifact. Before production use, replace environment-variable secret expressions with credentials, add explicit webhook authentication, add timeouts and retry/error branches, validate node versions, inspect the connection object after import, test safely, and publish only after verification.

Notifications#

The engine contains notification adapters for Mattermost, Slack, Teams, and SMTP email. Provider credentials belong in the runtime secret system. SMTP port 465 uses implicit TLS and 587 uses STARTTLS.

GitHub and GitLab#

Optional Cycle P links pull requests and board tickets. Configure the selected provider, repository, and provider token. There is no bundled SDK package for customers; integrations call the provider APIs from Python.

Idempotency#

The API does not define a general Idempotency-Key contract. Backlog proposal storage includes duplicate handling, and provider APIs may have their own concurrency controls, but callers must not assume every POST is safely repeatable. Confirm the existing run, proposal, or provider item before retrying a timed-out write.