FAQ
This page collects the most common questions developers ask while using Integration Center, organized into 4 categories. For scenario-specific questions (e.g. WeChat Pay callbacks, domain validation), refer to the FAQ section at the end of each integration guide.
| Category | For readers who | Questions |
|---|---|---|
| Basics | Are first-time users wanting to understand what an integration is | Q1 · Q2 |
| Usage and Limits | Have started using and hit edge cases | Q3 · Q4 · Q5 |
| Calling Integrations | Are coding against an integration function | Q6 · Q7 |
| Common Errors | Hit errors during onboarding or runtime | Q8 · Q9 · Q10 |
Basics
Q1: What's the difference between an "Integration" and a "Template"?
Integrations and templates are both ways CloudBase lets you reuse capabilities, but they have very different positioning:
| Aspect | Integration | Template |
|---|---|---|
| Nature | A platform-managed runtime service — the platform continuously runs an HTTP cloud function that interfaces with the third party for you | A code scaffold — you get a runnable starter project, own a copy and self-manage from then on |
| Credentials | ✅ Fill in third-party credentials (merchant ID, AppSecret, etc.) in the console; the platform injects them as env vars and stores them safely | ❌ No credential hosting; you put credentials in code or .env yourself |
| Callbacks | ✅ The platform automatically generates the callback domain + verify/decrypt pipeline; you only focus on business logic | ❌ Handle HTTPS, domain registration, signature verification yourself |
| Upgrades | ✅ Upgraded centrally by the platform (security patches, third-party protocol updates); no redeploy needed | ❌ Template code is now your asset — track upstream protocol changes yourself |
| Customization | Source is visible and extensible, but callback pipeline and credential injection are platform-managed | Fully open source — modify anything |
| Typical scenario | WeChat Pay, WeChat Official Account, Douyin Pay — third-party integrations needing long-term stability + frequent callbacks | Multi-tenant SaaS scaffolds, AI Bot starters, low-code starter packs — fast bootstrap projects |
How to choose?
- Need to integrate with WeChat Pay / Official Account and want to avoid managing credentials and verifying callbacks → use Integration
- Want a mature codebase as a starting point, freely customize, no platform dependency → use Template
Q2: Why does the integration's cloud function name have a random-string suffix? Can I rename it?
Integration Center generates the function name as <integration-name>-<random-string>. The random string is a platform-reserved identifier and cannot be modified, for two reasons:
- Avoid naming collisions between different integrations in the same environment
- It is bound to the callback subdomain and built-in environment variables — renaming will break the callback pipeline
If you want a stable name to reference in code, store the actual function name as a constant in your frontend code (like FN_NAME in this series of guides) — easy to swap.
Usage and Limits
Q3: Can I delete the cloud function generated by an integration directly?
Not recommended to delete it from the Cloud Function console — Integration Center will still keep the integration record and callback domain, but the function is gone, causing callbacks to fail.
The correct way is Integration Center → find the integration → click "Delete Integration": deleting the integration releases the callback domain and callback routes (cannot be recovered).
⚠️ Note: Deleting an integration only cleans up the callback pipeline. It does not automatically delete the generated cloud function (the function and all of its environment variables are an asset the platform generated for you and are fully preserved after the integration is deleted; you can keep customizing it / self-managing it, or go to the Cloud Function console to delete it manually). If you no longer need it, remember to clean it up separately.
Q4: Can I create multiple integrations of the same type in one CloudBase environment?
Yes. For example, in the same environment you can create two "WeChat Pay" integrations to connect with two different WeChat merchant accounts — they only need different integration names. Each integration generates its own cloud function and callback domain independently.
Q5: Can I customize the integration's cloud function code?
Yes. The integration function template is open-sourced in the official repository, and you can extend it for your business (e.g. add risk control before placing an order, write to your business DB after the callback). Two limits, however:
- Don't change the credential reading code — the platform-managed environment variable injection logic must stay intact
- Don't change the built-in callback paths (e.g.
/wechatpay/order) — otherwise callbacks will 404
If your customization exceeds these boundaries, switch to "Template" mode and self-manage from scratch.
Calling Integrations
Q6: Can integration functions be called by other cloud functions?
Yes. The integration function is essentially an HTTP cloud function and can be invoked from other cloud functions via tcb.callFunction / tcb.callContainer, etc. See the Cloud Function docs.
Q7: What authentication is required to call an integration function?
The cloud function generated by Integration Center is an HTTP cloud function — essentially a cloud function exposed over HTTPS. Calling it requires obtaining an access token and sending requests with an Authorization: Bearer <token> header.
Two typical patterns by caller:
| Caller | Authentication | Manual token management? |
|---|---|---|
| Mini Program | Use wx.cloud.callHTTPFunction — platform auto-authenticates and injects x-wx-openid | ❌ Not needed |
| Web/H5, server-side, third-party systems | Use the HTTP API: obtain an access_token first, then call with Authorization: Bearer <token> | ✅ Required |
Full guide to obtaining the access_token manually:
💡 In Web/H5 scenarios, if you've already integrated the CloudBase Auth Web SDK, the SDK manages the token lifecycle automatically and your business code can call the function directly. Manual token management is only needed for pure HTTP calls without the SDK.
Common Errors
Q8: Integration creation fails with "credential validation failed"
Usually a field is filled incorrectly. Check:
- Whether the field value is complete (especially PEM format:
-----BEGIN ...-----and-----END ...-----lines intact, internal newlines not corrupted) - Whether the credential type matches (e.g. WeChat Pay public-key mode and platform-certificate mode cannot be mixed)
- Whether the associated app (e.g. Mini Program AppID) is bound to the merchant ID
Q9: Calling the integration function returns 401
The caller did not provide a valid accessToken or openid:
- Mini Program scenario: confirm
wx.cloud.inithas been executed and the user has logged in to WeChat - Web scenario: the accessToken must come from authenticated login (anonymous login tokens have no permission to call cloud functions)
- HTTP scenario: refer to Q7 authentication guide and re-obtain the access_token
Q10: Third-party async notifications don't trigger the business function
Troubleshoot in this order:
- Is the callback URL filled in on the third-party platform set to the address generated by Integration Center?
- Are there matching records in "Callback Logs" on the integration detail page?
- If callback logs show signature verification failure: check credential consistency
- If the callback was forwarded to the function: check function logs to see whether the business code threw an error