RUNBOOK

• Agent-skill standard entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SKILL.md is also a navigation convention for larger skill docs.

1) Confirm OAuth Token Generation

• Use S2S credentials and account ID.
• Token endpoint: https://zoom.us/oauth/token.
• Refresh token before expiry.

Token Sanity Checks

• Verify token response is JSON and contains access_token.
• Record token expiry and refresh proactively.
• If auth intermittently fails, check for clock skew and stale cached tokens.

2) Confirm Subscription Configuration

• Event subscription created with WebSockets delivery type.
• Required event types selected and saved.

3) Confirm Connection URL and Auth

• Use exact WebSocket URL from Zoom subscription config.
• Attach access token as required by protocol/headers.

4) Confirm Runtime Reliability

• Implement reconnect with backoff.
• Handle heartbeat/ping-pong and connection lifecycle events.
• Prevent duplicate consumers if multiple workers run.

Minimal Reliability Policy

• Backoff: exponential with jitter.
• Cap retries and alert after sustained failures.
• Ensure only one active consumer per subscription stream in each environment.

5) Confirm Event Processing Semantics

• Handle ordering assumptions carefully.
• Make event handlers idempotent.
• Log event IDs and delivery timestamps.

6) Quick Probes

• Access token request succeeds and returns JSON.
• WebSocket connects and receives at least one subscribed event.
• Reconnect path works after forced disconnect.

Copy/Paste Validation Commands

Expected: token/API probes return JSON; websocket service logs show connect -> receive -> reconnect sequence.

7) Fast Decision Tree

• Connection refused/closed -> token invalid, wrong URL, or subscription config issue.
• Connected but no events -> wrong event selection or no triggering activity.
• Event storms/duplicates -> missing dedupe/idempotency logic.

8) WebSockets vs Webhooks Guardrail

• If your use case does not need persistent low-latency delivery, webhook delivery may be simpler to operate.
• Choose WebSockets when you can own connection lifecycle monitoring and reconnect behavior.