fix(pay): actionable webhook.verify errors for the raw-body mistake

[PancheI]

Problem

The most common "I can't verify AgentaOS webhooks" report is not a signing bug — it's integrators passing a parsed body instead of the raw request bytes (e.g. req.body after a global express.json()). The SDK stringified that object to "[object Object]" and surfaced a generic "Signature does not match payload", giving no clue what was wrong.

Verified against a real production webhook: signing is correct, webhooks.verify() is correct, and the docs already show express.raw(). The gap was purely the error message — so people file tickets instead of self-diagnosing.

Change (messages only — algorithm unchanged)

1. Reject a non-string/Buffer payload up front with an actionable message that names the received type and shows the fix:

   Webhook payload must be the raw request body (a string or Buffer), but received object. You are likely passing an already-parsed JSON body … Read the raw body instead, e.g. in Express: app.post('/webhooks', express.raw({ type: 'application/json' }), handler).

2. Add a raw-body hint to the signature-mismatch error, mirroring Stripe's "Are you passing the raw request body you received?".

Tests

+3 cases in webhooks.test.ts (parsed object → helpful error incl. express.raw, null → helpful error, genuine mismatch → hints at raw body). 15/15 pass, tsc --noEmit + biome clean. Changeset included (@agentaos/pay patch).

🤖 Generated with Claude Code