Agent skill
Hyperswitch Webhooks Skill
Receive and verify Hyperswitch webhooks (Juspay's open-source payments switch). Use when setting up Hyperswitch outgoing webhook handlers, debugging X-Webhook-Signature-512 verification (HMAC-SHA512 hex of the raw body keyed with payment_response_hash_key), deduplicating on event_id, or handling events like payment_succeeded, payment_failed, refund_succeeded and dispute_opened.
Install this skill
npx skills add hookdeck/webhook-skills --skill hyperswitch-webhooks
Hyperswitch is Juspay's open-source payments switch. Its outgoing webhooks report payment, refund, dispute, mandate, payout and invoice state changes to one endpoint per business profile and mode. Each delivery is an HTTP POST with a JSON body, signed in the X-Webhook-Signature-512 header.
This skill covers outgoing webhooks only. The same guide also describes incoming connector callbacks into Hyperswitch, which are out of scope here.
When to Use This Skill
- How do I receive Hyperswitch webhooks?
- How do I verify the
X-Webhook-Signature-512header? - Why does my Hyperswitch signature never match? (use the raw body and
payment_)response_ hash_ key - Why are my Hyperswitch deliveries unsigned? (the business profile has no hash key)
- How do I handle
payment_succeeded,refund_succeededordispute_opened? - How do I dedupe retried Hyperswitch webhooks on
event_id?
Setup Note
Set payment_response_hash_key on the Hyperswitch business profile and paste it here. Without it, deliveries are unsigned and fail verification. Live-mode webhook URLs must be allowlisted by Hyperswitch.
Steps are in references/setup.md.
Signature Verification (core)
| Header | X-Webhook-Signature-512 |
| Algorithm | HMAC-SHA512, lowercase hex digest (128 characters), no prefix |
| Key | The business profile's payment_, as UTF-8 bytes (not hex- or base64-decoded) |
| Signed content | The raw request body bytes only. No timestamp, id or other header |
The whole header value is one digest: don't split it or strip a prefix. There's no signed timestamp, so there's no replay window to check.
const crypto = require('crypto');
const SIGNATURE_PATTERN = /^[0-9a-fA-F]{128}$/;
function verifyHyperswitchSignature(rawBody, signatureHeader, secret) {
// Validate the format first: Buffer.from(x, 'hex') silently drops bad characters.
if (!signatureHeader || !SIGNATURE_PATTERN.test(signatureHeader)) return false;
const expected = crypto.createHmac('sha512', Buffer.from(secret, 'utf8')).update(rawBody).digest();
const received = Buffer.from(signatureHeader.toLowerCase(), 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
Python:
if not re.fullmatch(r"[0-9a-fA-F]{128}", signature_header or "", re.ASCII):
raise InvalidSignature
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha512).digest()
valid = hmac.compare_digest(bytes.fromhex(signature_header), expected)
Read the body as bytes, never as parsed JSON: express.raw({ type: '*/*' }) in Express, await request.arrayBuffer() in Next.js, await request.body() in FastAPI. A missing, empty or malformed header, or a mismatch, is a 401.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Event Types (event_type)
Dispatch on the top-level event_type. The guide lists 33 wire values:
| Group | event_type values |
|---|---|
| Payment | payment_succeeded, payment_failed, payment_processing, payment_cancelled, payment_, payment_authorized, payment_, payment_captured, payment_expired, action_required |
| Refund | refund_succeeded, refund_failed, refund_review |
| Dispute | dispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost |
| Mandate | mandate_active, mandate_revoked |
| Payout | payout_success, payout_failed, payout_initiated, payout_processing, payout_cancelled, payout_expired, payout_reversed, payout_not_permitted |
| Other | invoice_paid, surcharge_, surcharge_ |
The body has merchant_id, event_id, event_type and content (required), plus optional timestamp and processor_merchant_id. content.type (payment_details, refund_details, dispute_details, mandate_details, payout_details, subscription_details) names the resource shape in content.object; it's a coarser grouping, not the event. The guide publishes no example body, so check a real delivery before relying on field names inside content.object. See references/overview.md.
Handler Rules
- Verify the raw bytes, then parse. Re-serialised JSON won't match.
- Return
2xxonly once you've accepted the event. Hyperswitch retries anything else: 16 retries over about 24 hours. - Dedupe on
event_id. Retries can deliver the same event twice; acknowledge a duplicate without re-applying it. - Don't assume order. For payments, compare
content.object.updatedwith the stored value and apply only newer state. - Log and acknowledge unknown events. Handle the common ones and ignore the rest.
Environment Variables
# The business profile's payment_response_hash_key (used as UTF-8 bytes)
HYPERSWITCH_WEBHOOK_SECRET=your_payment_response_hash_key
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 hyperswitch --path /webhooks/hyperswitch
Reference Materials
- references/overview.md: Events, payload shape, delivery and retries
- references/setup.md: Business profile hash key, endpoint URL, live-mode allowlisting
- references/verification.md: HMAC-SHA512 details, common mistakes, debugging