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>

Send the Unix timestamp in X-ScrumPulse-Timestamp. Build the signed bytes by concatenating v1:, the timestamp, :, the organization ID, :, and the exact raw request body. Send the resulting HMAC-SHA256 hex digest as v1=<digest> in X-ScrumPulse-Signature.

The server rejects signatures older than five minutes by default, signatures copied to a different organization URL, and requests where CHAT_WEBHOOK_SIGNING_SECRET is missing. A matching Clerk organization identity is the alternate authenticated path.

import hashlib
import hmac
import time

timestamp = str(int(time.time()))
message = f"v1:{timestamp}:{org_id}:".encode() + raw_body
digest = hmac.new(signing_secret.encode(), message, hashlib.sha256).hexdigest()
headers = {
    "X-ScrumPulse-Timestamp": timestamp,
    "X-ScrumPulse-Signature": f"v1={digest}",
}

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.

SES bounce and complaint webhook#

Endpoint:

POST /api/webhooks/ses

AWS SNS posts SES bounce and complaint events here. The handler verifies the AWS signature, accepts certificates and subscription URLs only from HTTPS SNS hosts without following redirects, requires the configured SES_SNS_TOPIC_ARN in production, and records each MessageId in a bounded replay ledger. Replayed events return a duplicate acknowledgement without changing suppression state.

The deployment-wide suppression feed at GET /api/email/suppressions and its delete route accept only the server-side X-API-Key system credential. Clerk organization roles do not grant access because the feed contains email addresses across tenants. The response intentionally omits SMTP diagnostic text.

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.