Agent skill

Coinbase Commerce Webhooks Skill

Receive and verify Coinbase Commerce webhooks. Use when setting up Coinbase Commerce webhook handlers, debugging X-CC-Webhook-Signature verification, or handling cryptocurrency payment events like charge:created, charge:confirmed, charge:failed, charge:pending, charge:delayed, and charge:resolved.

Install this skill

npx skills add hookdeck/webhook-skills --skill coinbase-commerce-webhooks

When to Use This Skill

Setting up Coinbase Commerce webhook handlers for cryptocurrency payments
Debugging X-CC-Webhook-Signature verification failures
Understanding Coinbase Commerce charge event types and payloads
Handling charge:confirmed, charge:failed, or charge:pending events

Verification (core)

Coinbase Commerce signs the raw request body with HMAC-SHA256 keyed on your webhook shared secret and sends the hex digest in the X-CC-Webhook-Signature header. Verify against the raw body (never the parsed JSON) and compare timing-safe. The event object is nested under the event key in the body.

Node — use the official coinbase-commerce-node SDK:

const { Webhook } = require('coinbase-commerce-node');

// Throws SignatureVerificationError on mismatch; returns the verified event.
// rawBody MUST be the raw request body string, not re-serialized JSON.
const event = Webhook.verifyEventBody(rawBody, signature, sharedSecret);
console.log(event.type, event.data.id); // e.g. "charge:confirmed"

Manual (any language) — HMAC-SHA256 hex of the raw body, timing-safe compare:

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

For complete handlers with route wiring, event dispatch, and tests, see:
examples/express/
examples/nextjs/
examples/fastapi/

Common Event Types

Event	Triggered When
`charge:created`	A new charge is created
`charge:pending`	Customer paid; payment detected on-chain but not yet confirmed
`charge:confirmed`	Payment confirmed — the charge is complete
`charge:failed`	The charge failed or expired without full payment
`charge:delayed`	Payment arrived late or was underpaid/overpaid
`charge:resolved`	A previously delayed charge has been resolved

For full event and payload reference, see references/overview.md.

Important Headers

Header	Description
`X-CC-Webhook-Signature`	HMAC-SHA256 (hex) of the raw request body

Environment Variables

COINBASE_COMMERCE_WEBHOOK_SECRET=your_webhook_shared_secret   # Settings > Notifications

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 coinbase-commerce --path /webhooks/coinbase-commerce

Reference Materials

references/overview.md - Coinbase Commerce webhook concepts and events
references/setup.md - Dashboard configuration and shared secret
references/verification.md - Signature verification details and gotchas