Documentation Index
Fetch the complete documentation index at: https://docs.cello.so/llms.txt
Use this file to discover all available pages before exploring further.
The Integration Status page gives you a single health view of your Cello integration. It tracks four core components - the Referral component, the Attribution library, Signups tracking, and Purchases tracking - and tells you at a glance whether each one is sending events as expected.
Use Integration Status to confirm a new integration is wired up correctly, monitor an existing integration in production, and quickly spot when an upstream change has broken a webhook or script.
You can access it at Integrations → Integration Status in the Cello Portal. It’s available in both sandbox and production.
How it relates to Event Feed
Integration Status and the Event Feed work hand-in-hand:
- Integration Status - high-level health per component. Use it to answer “is everything working?”
- Event Feed - individual event log with per-field validation. Use it to answer “why did this specific event fail?”
When a component on Integration Status shows a warning or error, the Event Feed is where you drill in to see the exact payload and field-level issue.
The page header gives you an at-a-glance summary of your integration before you scroll into the individual component cards.
| Field | What it shows |
|---|
| Environment | Which environment you’re viewing - Sandbox or Production. |
| Status | Aggregate health across all four components (e.g. 4/4 connected, 2/4 need attention). |
| Health window | The time range Cello checks for successful events. If none arrive within this window, the integration is flagged as needing attention. The window is 1 hour in production and 24 hours in sandbox. |
| Last update | Time since the page last refreshed its data. Use the refresh icon to re-check all components on demand - otherwise, statuses refresh automatically within ~10 minutes of an event arriving. |
| Update configuration | Opens the modal where you can change the signup and purchase sources. See Changing the configured source. |
Status definitions
Every component reports one of three statuses, calculated against the health window shown in the page header (1 hour in production, 24 hours in sandbox):
| Status | Meaning |
|---|
| Connected | At least one successful event received within the health window. Even if some events had errors, a single success is enough to count as Connected. |
| Connected with warnings | Events were received in the last 30 days but none in the current health window, or events arrived in the health window but had validation issues. |
| Not connected | No events from this source in the last 30 days, or the source has not been configured. |
The four components
1. Referral component
Tracks booted events from cello.js - the script that renders the Referral Component widget in your app.
The card shows when the last event and last error were received. When errors are present, the alert summarizes the most recent error and a View all errors link opens the last 10 widget events so you can see what went wrong.
| Status | What it means | What to check |
|---|
| Connected | The Referral Component booted successfully within the health window. | Nothing - everything is working as expected. |
| Connected with warnings | No successful boots in the health window, but no errors either. | Confirm the Referral Component is still being loaded for users. Check whether traffic to pages embedding the widget has dropped. |
| Connected with warnings (errors present) | Recent boots produced errors. The card shows the last error message and links to the last 10 widget events. | See Widget errors reference below to interpret the message. |
| Not connected | No boots in 30 days. | Verify cello.js is loaded and cello("boot", ...) is called. See Embed the Referral Component. |
| Error type | Console (browser) | API (network tab) | Portal |
|---|
| JWT token issue | 401 (Unauthorized) [Cello]: User is not authorized to load the widget | Error 1100: Invalid JWT token | JWT token is missing, malformed, or expired (code: Invalid token payload) |
| Internal error | Internal server error | Internal server error | An internal error occurred - contact support |
Token issue (InvalidJwt)
The portal collapses several underlying token failures into a single message: “JWT token is missing, malformed, or expired”. The actual underlying cause is one of:
token verification failed - decodeWidgetToken could not verify the signature.token schema not validated - the token payload is invalid (e.g. wrong shape).token missing iat field - the token has no iat claim and allowMissingTokenIat = false.token creation time in future - the iat is in the future.No referrer found for productUserId - the token references a productUserId that doesn’t exist.No auth token found - no token was sent with the boot request.
If the portal shows this error, regenerate the widget token on your backend and confirm it’s signed with the right secret, contains a valid productUserId, and has a current iat timestamp. See User Authentication for details.
2. Attribution library
Tracks referral link visits picked up by cello-attribution.js - the script you embed on your landing pages to capture referral codes.
| Status | What it means | What to check |
|---|
| Connected | A referral link was visited within the health window. | Nothing - attribution is being captured. |
| Connected with warnings | No referral link visits in the last few hours. | Likely just low traffic. Check sharing activity in the portal. |
| Not connected (no signup URL) | No signup URL is set in your Cello configuration. | Set the signup URL in User Experience → Settings. |
| Not connected (URL set, no events) | The signup URL is configured but no visits have been recorded. | Confirm cello-attribution.js is embedded on the landing pages reachable from your referral links. See Web attribution setup. |
3. Signups tracking
Tracks signup events from your configured source. The expected event type depends on which source you use:
| Source | Events tracked |
|---|
| Cello API | new-signup |
| Stripe | customer.created, customer.updated |
| Chargebee | Customer Created, Customer Changed |
| Auto Attribution | Signup detected by Auto Attribution (only used if no other source is set) |
The card shows the configured source, when the last attributed signup event was received (i.e. the last event that included a referral code), and a Change link to update the source. When the card needs attention, the alert links directly to the Event Feed so you can drill into the offending events.
Common alerts
| Status / Source | Alert | What to do |
|---|
| Not connected - Cello API | No new-signup events received from Cello API. | Confirm your backend is calling POST /events with trigger: "new-signup". See Track Signups. |
| Not connected - Stripe | No customer.created / customer.updated events from Stripe. | Confirm the Stripe webhook is installed and pointed at the right Cello endpoint. |
| Not connected - Chargebee | No Customer Created / Customer Changed events from Chargebee. | Confirm the Chargebee webhook is configured. |
| Not connected - Auto Attribution | No signups detected. | Verify Auto Attribution is enabled and a signup has actually occurred. |
| Not configured | Event source is not set. | Set the source from the Update configuration modal (sandbox), or contact Cello Support (production). |
| Missing API key | Cello API key has not been generated. | Generate an API key in Integrations → API Keys. |
| Missing webhook | The webhook for the selected source has not been installed. | Follow the webhook setup guide for your provider. |
| Connected with warnings - events received, none attributed | ”We are receiving events from [source], but no attributed events in the last [health window]. Go to the events page.” | Events are arriving but none include a referral code (ucc), so they can’t be attributed. Open the Event Feed (linked directly from the alert) and inspect the recent events to see which ucc values are missing or malformed. |
| Connected with warnings - attributed events have errors | All attributed events received in the health window failed validation. | Open the Event Feed and inspect the recent attributed events to see which required fields are failing. |
4. Purchases tracking
Tracks purchase events from your configured source:
| Source | Events tracked |
|---|
| Cello API | invoice-paid |
| Stripe | Purchase events (e.g. invoice.paid, charge.succeeded) |
| Chargebee | Purchase events |
The card shows the configured source, when the last attributed purchase event was received (i.e. the last event that included a referral code), and a Change link to update the source. When the card needs attention, the alert links directly to the Event Feed so you can drill into the offending events.
Common alerts
| Status / Source | Alert | What to do |
|---|
| Not connected - Cello API | No invoice-paid events received from Cello API. | Confirm purchase events are being sent. See Track Purchases. |
| Not connected - Stripe | No purchase events from Stripe. | Confirm the Stripe webhook is forwarding purchase events. |
| Not connected - Chargebee | No purchase events from Chargebee. | Confirm the Chargebee webhook is forwarding purchase events. |
| Not configured | Event source is not set. | Set the source from the Update configuration modal (sandbox), or contact Cello Support (production). |
| Connected with warnings - events received, none attributed | ”We are receiving events from [source], but no attributed events in the last [health window]. Go to the events page.” | Events are arriving but none include a referral code (ucc), so they can’t be attributed. Open the Event Feed (linked directly from the alert) and inspect the recent events to see which ucc values are missing or malformed. |
| Connected with warnings - attributed events have errors | All attributed events received in the health window failed validation. | Open the Event Feed and inspect the recent attributed events to see which required fields are failing. |
- Signup source - Cello API, Stripe, Chargebee, or Auto Attribution.
- Purchase source - Cello API, Stripe, or Chargebee.
When you change a source, the corresponding component on Integration Status will revert to Not connected until events from the new source start arriving.
Sandbox vs production
| Environment | Who can change the configuration |
|---|
| Sandbox | You can change the signup and purchase sources yourself while testing your integration. |
| Production | Source configuration in production is handled by Cello Support. Reach out whenever you need to set or change a production source. |
Auto Attribution
Auto Attribution can only be enabled by Cello Support. Once enabled for your tenant, Auto Attribution appears as a selectable option in the Signup source dropdown.
If Auto Attribution is on but a CRM source (Cello API, Stripe, or Chargebee) is selected as the primary signup source, Auto Attribution runs in the background to catch any signups missed by the primary source.
Troubleshooting
| Problem | Cause | Solution |
|---|
| Component shows Not connected even though events are flowing | Status updates can take up to 10 minutes | Click the refresh icon next to Last update to re-check immediately. |
| Component shows Connected with warnings but you can’t see why | The summary doesn’t include payload-level detail | Open the Event Feed to inspect the latest events for that source. |
| Signup or Purchase tracking shows “source not set” | No source has been configured for this tenant | Set the source from the Update configuration modal in sandbox, or contact Cello Support to configure it for production. |
| Status flipped to Not connected after you updated your integration | Source was changed and no new events have arrived yet | Trigger a test event from the new source - the status will update within ~10 minutes. |
| Auto Attribution doesn’t appear in the Signup source dropdown | Auto Attribution has not been enabled for your tenant | Contact Cello Support to enable Auto Attribution. |
