Setup Zoom Webhooks

Webhooks 5-Minute Preflight Runbook

Use this before deep debugging. It catches common webhook failures quickly.

Skill Doc Standard Note

• 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 Endpoint Reachability

• Public HTTPS endpoint is reachable from Zoom.

• Reverse proxy routes to the correct service path.

2) Confirm Signature Verification

• Verify x-zm-signature with raw request body.

• Use x-zm-request-timestamp and reject stale timestamps.

• Do not re-serialize parsed JSON for signature material.

Signature Formula Reminder

payload = "v0:" + x-zm-request-timestamp + ":" + raw_body
expected = "v0=" + HMAC_SHA256(webhook_secret, payload)

If raw_body differs from original bytes (pretty print/re-stringify), verification fails.

3) Confirm URL Validation Handling

• Handle endpoint.url_validation challenge correctly.

• Return expected plainToken and computed encryptedToken when required.

URL Validation Reminder

On event = endpoint.url_validation, hash payload.plainToken with your webhook secret and return both values exactly.

4) Confirm Event Subscription Setup

• Feature/Event subscriptions enabled in app config.

• Required event types selected and saved.

5) Confirm Processing Pattern

• Respond HTTP 200 quickly.

• Process business logic asynchronously.

• Make handlers idempotent for retries.

6) Quick Probes

• Local test payload verifies signature path.

• Zoom test event reaches endpoint and is logged.

• No repeated non-200 responses in logs.

Copy/Paste Validation Commands

# 1) Reachability check (replace with your webhook route)
curl -sS -i "https://your-domain.example/webhook"

# 2) Check service logs quickly while sending test events
# (replace command with your runtime: pm2/docker/systemd)
pm2 logs your-service --lines 100

# 3) Basic endpoint health check if available
curl -sS -i "https://your-domain.example/health"

Expected: endpoint is reachable over HTTPS, events appear once, and responses are consistently 2xx.

7) Fast Decision Tree

• No events received -> endpoint unreachable or wrong subscription.

• 401 invalid signature -> raw body mismatch/secret mismatch.

• Duplicate events -> no idempotency or delayed responses.

8) Retry and Idempotency Guardrail

• Treat webhook delivery as at-least-once.

• Deduplicate by event ID/timestamp/resource key before side effects.

• Keep handlers safe to re-run.