Skip to main content
When something isn’t working as expected, a systematic approach gets you to the root cause fastest: check the error code or message first, consult the relevant section below, and verify in the audit log or delivery history whether the problem is in mFoundry or in a downstream system. Most issues fall into one of four categories — authentication, webhooks, integrations, or performance — and each has clear diagnostic steps you can work through without waiting for support. If you exhaust the steps here and the issue persists, the team is ready to help.
Still stuck? Email support@mfoundry.io or open a support ticket directly from the dashboard by clicking the Help icon in the bottom-left navigation and selecting Open a Ticket. Include the error code, affected resource ID, and approximate time of the incident to help the team respond faster.

​
Authentication Issues

Authentication failures surface as HTTP 401 or 403 responses and almost always come down to a key problem or a permissions mismatch. Debugging tip: Pass the -v flag with cURL or inspect the WWW-Authenticate response header — mFoundry includes a machine-readable error code and a human-readable message in every 4xx response body:

​
Webhook Failures

Webhook delivery problems fall into three categories: the endpoint is unreachable, the signature doesn’t match, or your endpoint can’t parse the payload. Checking delivery logs: Open Settings > Webhooks, click the webhook in question, and select the Delivery History tab. Each entry shows the event type, delivery timestamp, HTTP response code your endpoint returned, and the full response body. Use this log as your first stop — it tells you exactly what mFoundry sent and how your endpoint responded. Endpoint unreachable:
  • Confirm the endpoint URL is publicly accessible. mFoundry cannot reach internal or localhost addresses.
  • Check that your server or load balancer accepts POST requests and does not redirect HTTPS to HTTP (mFoundry does not follow redirects).
  • Verify TLS certificate validity — expired or self-signed certificates cause connection failures.
  • Temporarily use a tool like Webhook.site as a test endpoint to confirm mFoundry is sending the payload correctly.
Signature mismatch:
  • Ensure you are computing the HMAC using the raw, unparsed request body — not a re-serialized JSON object. Parsing and re-stringifying changes whitespace and key order, which alters the signature.
  • Confirm you are using the correct secret key for this specific webhook. Each webhook has its own unique secret.
  • See Verifying Signatures for the reference Node.js implementation.
Payload parsing errors:
  • Verify your endpoint reads the Content-Type: application/json header and parses the body as JSON.
  • Check for middleware (e.g., body-parser or framework defaults) that may consume or transform the raw body before your signature verification code runs.

​
Integration Problems

Native integrations (Slack, GitHub, Jira) use OAuth tokens that can expire or lose their granted scopes. OAuth token expired: Symptoms: the integration shows a red Disconnected badge in Settings > Integrations, or workflow steps using the integration return authorization errors in their run logs. To re-authorize:
1

Open Settings > Integrations

Navigate to Settings > Integrations and locate the affected integration.
2

Click Reconnect

Click Reconnect (or Re-authorize) next to the integration. You are redirected to the provider’s OAuth consent screen.
3

Grant the required permissions

Sign in to the provider and approve the requested scopes. mFoundry displays the exact permissions it needs — do not deselect any listed scope or the integration will partially fail.
4

Confirm the connection

After approving, you are redirected back to mFoundry. The integration status changes to Connected. Trigger a test workflow to confirm the connection is working end to end.
Scope mismatch: If you previously authorized with fewer scopes than mFoundry now requires (due to a feature update), the integration status shows a Scope Warning badge. Follow the same reconnection steps above — the OAuth prompt will request the additional scopes. If you are not the account owner on the provider side, coordinate with whoever manages those credentials.

​
Performance

Slow API responses:
  • Check the mFoundry Status Page first — elevated response times during a platform incident are not something you can resolve locally.
  • Reduce payload size by using field selection parameters where available to fetch only the properties your application needs.
  • Cache responses for resources that change infrequently (e.g., organization settings, member lists) rather than fetching them on every request.
  • Move non-critical API calls to background jobs so they don’t block user-facing request paths.
Rate limit errors (429): The Retry-After header on a 429 response tells you exactly how many seconds to wait. Honor it — retrying sooner resets the backoff and prolongs the lock-out window.