Skip to main content

Integration Issues

This guide covers problems with cross-product integrations, Entity Sync, the event bus, webhooks, and API connectivity.

Entity Sync Conflicts​

Symptom: A company or contact appears duplicated, or changes in one product are not reflected in another.

Understanding Entity Sync​

Entity Sync keeps companies and contacts consistent across PSA, CRM, Books, RMM, Security, Portal, CMDB, and Voice. Changes propagate via the event bus and are typically reflected within seconds.

Debugging Steps​

  1. Check the Entity Sync dashboard — Go to Hub > Integrations > Entity Sync to see the sync status and any conflicts.
  2. Review the conflict — When two products modify the same entity simultaneously, a conflict is created. Open the conflict to see both versions and choose which to keep.
  3. Force a resync — Select the entity and click "Resync" to push the current Hub version to all connected products.
  4. Check for duplicates — If the same company was created independently in two products before Entity Sync was enabled, duplicates may exist. Use the "Merge" function to combine them.

Common Causes​

  • Race conditions — Two users editing the same entity in different products at the same time.
  • Delayed bus events — During high-traffic periods, sync events may be delayed by a few seconds.
  • Partial product setup — If a product was added to your subscription after initial setup, existing entities may not have synced yet. Run a full sync from the Entity Sync dashboard.

Bus Event Failures​

Symptom: Actions in one product are not triggering expected actions in another (e.g., a new PSA ticket is not showing in the Portal).

Debugging Steps​

  1. Check the Event Log — Go to Hub > Integrations > Event Log to see recent bus events and their delivery status.
  2. Look for failed deliveries — Failed events will show a red status. Click to see the error details.
  3. Verify the integration is enabled — Go to Hub > Integrations and confirm the relevant cross-product integration is toggled on.
  4. Check product subscriptions — Both the source and destination products must have active subscriptions for events to flow between them.

Common Event Types​

EventSourceDestinationPurpose
ticket.createdPSAPortal, HubNew ticket notification
alert.triggeredRMM, SecurityPSA, On-CallAuto-create ticket or page on-call
company.updatedAnyAll synced productsEntity Sync
invoice.createdBooksPortal, HubClient invoice notification

Cross-Product Data Not Appearing​

Symptom: Data from one product is not showing up where you expect it in another product.

Debugging Steps​

  1. Verify entitlements — Both products must be active in your subscription.
  2. Check the integration toggle — Go to Hub > Integrations and verify the specific integration is enabled.
  3. Check user permissions — The user viewing the data needs permissions in both the source and destination products.
  4. Wait and refresh — Cross-product data propagation can take up to 30 seconds in some cases. Refresh the destination product page.
  5. Check the Dashboard Widgets — If the issue is with the Hub dashboard, go to Hub > Dashboard > Edit and verify the relevant product widget is added to your layout.

Webhook Delivery Failures​

Symptom: External systems are not receiving webhook payloads from The One Stack.

Debugging Steps​

  1. Check the webhook log — Go to Hub > Integrations > Webhooks and review the delivery log for your webhook endpoint.
  2. Verify the endpoint URL — Ensure the URL is correct and publicly accessible (not behind a firewall or VPN).
  3. Check the response code — The One Stack expects a 2xx response within 10 seconds. Timeouts or non-2xx responses are treated as failures.
  4. Verify the secret — If you configured a webhook secret for signature verification, ensure the receiving system is using the correct secret to validate the X-Webhook-Signature header.

Retry Policy​

Failed webhook deliveries are retried automatically:

  • 1st retry — 1 minute after failure
  • 2nd retry — 5 minutes after failure
  • 3rd retry — 30 minutes after failure
  • Final retry — 2 hours after failure

After all retries are exhausted, the webhook is marked as failed. You can manually retry from the webhook log.

API Key Permissions​

Symptom: API requests return 403 Forbidden even though you have a valid API key.

Debugging Steps​

  1. Check the key's scope — Go to Hub > API Keys and verify the key has permissions for the product and action you are trying to use.
  2. Check the key's status — Ensure the key has not been revoked or expired.
  3. Verify the product — API keys are scoped to specific products. A key created for PSA will not work for CRM endpoints.
  4. Check rate limits — If you are making many requests, you may have hit the rate limit. Check the X-RateLimit-Remaining response header.
  5. Verify the base URL — Each product has its own API base URL. Ensure you are using the correct one for the product you are targeting.