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

```text
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

```bash
# 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.


---
name: setup-zoom-webhooks
description: Reference skill for Zoom webhooks. Use after routing to an event-driven workflow when implementing subscriptions, signature verification, delivery handling, retries, or event-type selection.
triggers:
  - "zoom webhook"
  - "webhook signature"
  - "x-zm-signature"
  - "event subscription"
  - "recording completed webhook"
---

# /setup-zoom-webhooks

Background reference for Zoom event delivery over HTTP. Prefer workflow skills first, then use this file for verification, subscription, and delivery details.

## Prerequisites

- Zoom app with Event Subscriptions enabled
- HTTPS endpoint to receive webhooks
- Webhook secret token for verification

> **Need help with authentication?** See the **[zoom-oauth](../oauth/SKILL.md)** skill for OAuth setup.

## Quick Start

```javascript
// Express.js webhook handler
const crypto = require('crypto');

// Capture raw body for signature verification (avoid re-serializing JSON).
app.use(require('express').json({
  verify: (req, _res, buf) => { req.rawBody = buf; }
}));

app.post('/webhook', (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-zm-signature'];
  const timestamp = req.headers['x-zm-request-timestamp'];
  const body = req.rawBody ? req.rawBody.toString('utf8') : JSON.stringify(req.body);
  const payload = `v0:${timestamp}:${body}`;
  c