Events, webhooks and API reference
Only document endpoints and events that actually exist.
Events, webhooks and API reference
VELORYZ Studio · Integrations and developer reference Audience: Developers, technical leads and administrators Guide type: Practical Studio operations guide
Purpose
Events, webhooks and API reference should be treated as an end-to-end responsibility, not an isolated button. Start by defining what will change, who can approve it and how success will be checked. Only document endpoints and events that actually exist.
Do not promise a stable public webhook or API without published authentication, versioning and rate-limit contracts.
Availability and responsibility
The source uses a Next/Vinext-style app, Cloudflare runtime bindings, an owner CMS, media storage, protected API routes and optional provider connections. Do not interpret a conceptual API topic as a public stable API contract.
Before committing time or budget, confirm who operates this workflow: the visitor, the client portal user, a Studio owner, or the delivery team. A feature described in design documentation is not automatically a public account entitlement.
Before you begin
- A documented use case, data-flow diagram and owner of the integration
- Authentication model, test credentials stored securely, rate-limit expectations
- Failure handling, monitoring, maintenance and rollback requirements
- A short list of measurable success criteria specifically for events, webhooks and api reference.
- A recovery plan if the proposed change creates a regression.
Recommended procedure
- Locate the relevant area or public route. For new projects, establish the brief at /create/; for owner-only content changes, use authenticated Studio Control at /admin. Do not assume a missing feature exists.
- Define the specific work item for Events, webhooks and API reference: capture the initial state, user intent, relevant data, permissions, expected output and what must not change.
- Follow the design and operating decisions listed below. Work in a draft, staging or reviewed project handoff where available; avoid editing live customer data experimentally.
- Review the effect with real content and realistic viewport sizes. Record any exception and obtain the appropriate approval before a public change.
- After the change, verify the public outcome rather than relying on a success message alone; preserve a reference to the reviewed version.
Topic-specific operating procedure
These steps apply to Events, webhooks and API reference. The implementation must be verified against the current Studio permissions, deployed provider connections and approved project scope.
- Only document deployed API routes after checking method, authentication, validation and response shape.
- Define contract version, rate limits, pagination, error codes and webhook signature policy if applicable.
- Avoid exposing internal administrative endpoints as a public developer API.
- Publish examples with safe test data and verify them against a real staging service.
Evidence to retain
- The original input or situation, and a clear before/after comparison.
- The reviewed version, responsible owner and acceptance record.
- Any limitation, follow-up decision, or safely reversible workaround.
Configuration and decision points
- Start with the relevant /developers/ reference and inspect the actual repository route and API handler.
- Define request/response schemas, ownership boundaries and permission checks before connecting a service.
- Keep secrets server-side; test in a nonproduction environment with realistic invalid inputs.
- Record deployment settings, migrations, operational ownership and recovery procedures.
When more than one implementation is possible, prefer the simplest approach that remains accessible, maintainable and compatible with the current source. Note any cost, licensing, privacy, ownership and performance implications before approval.
Verification checklist
- External calls validate origin and input and do not expose privileged operations publicly.
- Timeouts, quotas and retries do not create duplicate project or payment actions.
- Logs avoid credentials and private client data.
- Integration behavior is verified end to end, not inferred from source comments alone.
Also confirm that the result addresses the original objective: Only document endpoints and events that actually exist.. Review the customer-visible language, error states, navigation paths and the relevant device widths. A green build or a successful save does not by itself establish a correct production outcome.
Troubleshooting and recovery
- If a service is unavailable, degrade gracefully or provide a clear alternative.
- If credentials rotate, invalidate old secrets and retest connection flows.
- If an API contract changes, version documentation and consumers together.
When asking for assistance, include the exact public URL or project reference, a concise reproduction path, the expected behaviour, actual behaviour, relevant timestamps and a redacted screenshot if useful. Never include passwords, access tokens or private customer records.
Related reading
- [Integrations overview](/docs/studio/integrations/overview/)
- [Forms and notification integrations](/docs/studio/integrations/forms-notifications/)
- [Embed external services](/docs/studio/integrations/embeds/)
- [All VELORYZ documentation](/docs/)
- [Studio documentation](/docs/studio/)
- [Help Centre](/help/studio/)
- [/create/](/create/)
- [/docs/overview/](/docs/overview/)
Operational note
This article describes the Studio workflow and its acceptance criteria. Where a self-service control is not available, the action is coordinated with the Studio team rather than silently represented as automated.
