feat: add vapi-webhooks skill

[garethx]

Summary

Adds a webhook skill for Vapi (voice-AI agent platform — the "Server URL"). Collision check clean: no prior vapi-webhooks skill or providers.yaml entry.

Authored from Vapi's canonical docs (server-url, events, server-authentication). This one needed care rather than a stock HMAC template — Vapi has no fixed signature scheme, so the skill is written to avoid fabricating a construction.

Why this skill is unusual

• Auth is opt-in and per-endpoint. A Server URL has no auth until you attach a Custom Credential. Four types exist: Bearer Token, legacy X-Vapi-Secret, OAuth 2.0, and a fully-configurable HMAC.
• Primary path = shared secret (Authorization: Bearer <token> or legacy X-Vapi-Secret) — a literal, timing-safe compare, not an HMAC. The examples implement this and read whichever header is present.
• HMAC is documented generically, not hardcoded. Vapi lets the customer choose the algorithm, header name, optional timestamp header, and payload format, and pins no defaults — so references/verification.md refuses to assert one. OAuth 2.0 is covered as the token-validation path.
• No fabricated helper. A verifyVapiSignature name in a CLI tutorial is an unimplemented placeholder — the skill explicitly does not use it. No official SDK verify helper exists; no documented source-IP allowlist.
• Nested envelope. The event type is at message.type, not top-level (a CLI tutorial shows a flatter shape with names like call-started — that's informal example code, not the wire format; the skill follows /server-url/events).
• Bidirectional request/response protocol. Four message types require a JSON response body, which the handlers implement: assistant-request (hard ~7.5s timeout), tool-calls, transfer-destination-request, knowledge-base-request. All other types get a bare 200.

Tests

• Express: 19 passed
• Next.js: 14 passed
• FastAPI: 18 passed
• validate-provider.sh vapi-webhooks: passed

Auth tests cover both the Bearer and legacy X-Vapi-Secret headers, wrong/missing secret → 401, and the required response bodies for all four request/response types.

Notes for the reviewer

• Not live-verified. Authored from docs, not a captured delivery (no Vapi test account in this run). Residual unknowns — exact HMAC construction (undocumented by design), precise response shapes, and the ~7.5s budget — are recorded in skills/vapi-webhooks/TODO.md for a future live pass.

Left as a draft pending sign-off.

🤖 Generated with Claude Code