Troubleshooting

Webhook signature verification keeps failing

Cause

The most common cause is verifying against a parsed/re-serialized body instead of the exact raw request bytes — JSON.stringify(JSON.parse(body)) does not always reproduce the original byte string. A second common cause is comparing signatures with === instead of a timing-safe comparison, or using the wrong endpoint secret (each endpoint has its own).

Fix

Verify against req.text() (the raw body) before any JSON parsing, use crypto.timingSafeEqual, and confirm you're using the secret shown for that specific endpoint. See the Verification section on the Webhooks page.

Getting 429 Too Many Requests

Cause

You've exceeded your plan's per-minute or per-day request limit on the REST API.

Fix

Check the Retry-After header and back off accordingly. If you're consistently hitting the limit, batch reads with pagination (limit=100) instead of one request per record, or upgrade your plan — limits scale with plan tier.

Module submission won't leave DRAFT

Cause

Validation runs automatically before a submission can enter the review queue — the most common failures are a moduleKey that isn't lowercase kebab-case, a description under 50 characters, a workflowTrigger not in entity.event format, or a reserved key prefix (botforge_, official_, platform_, bf_, admin_, system_).

Fix

Check the specific validation error returned by createSubmission()/submitForReview() — it names the failing field. Full rules are on the SDK page's Validation Rules.

"Continue with SSO" doesn't appear on login

Cause

The domain-discovery banner only appears when the email's domain matches a VERIFIED OrganizationDomain whose organization has an ACTIVE IdentityProvider. An unverified domain, or an IdentityProvider left in a non-ACTIVE state, silently suppresses the banner rather than erroring.

Fix

In the Enterprise Identity page, confirm the domain shows VERIFIED and the identity provider shows ACTIVE. Domain verification (DNS TXT record) must complete before SSO discovery activates for that domain.

A channel adapter isn't sending or receiving messages

Cause

Some platforms (Reddit today) are registered but their adapter is a stub — isAdapterReady() returns false and no webhook parsing/outbound sending is implemented yet, regardless of any credentials you provide.

Fix

Check the platform's status on the Channels reference — only platforms marked Live have a working adapter. Coming Soon / Planned platforms have no functional connection yet.

A workflow never fires

Cause

The trigger type doesn't match what's actually emitted — either a typo in a custom module's workflowTriggers declaration, or the workflow is still Disabled.

Fix

Confirm the workflow is enabled, and that its trigger type exactly matches one in the merged trigger list (built-in + your installed modules' declarations) shown in the Workflow Builder's palette — that list is always the authoritative set of what can actually fire.