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-512 header?
  • 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_succeeded or dispute_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)

HeaderX-Webhook-Signature-512
AlgorithmHMAC-SHA512, lowercase hex digest (128 characters), no prefix
KeyThe business profile's payment_response_hash_key, as UTF-8 bytes (not hex- or base64-decoded)
Signed contentThe 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:

Groupevent_type values
Paymentpayment_succeeded, payment_failed, payment_processing, payment_cancelled, payment_cancelled_post_capture, payment_authorized, payment_partially_authorized, payment_captured, payment_expired, action_required
Refundrefund_succeeded, refund_failed, refund_review
Disputedispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
Mandatemandate_active, mandate_revoked
Payoutpayout_success, payout_failed, payout_initiated, payout_processing, payout_cancelled, payout_expired, payout_reversed, payout_not_permitted
Otherinvoice_paid, surcharge_payment_succeeded, surcharge_refund_succeeded

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

  1. Verify the raw bytes, then parse. Re-serialised JSON won't match.
  2. Return 2xx only once you've accepted the event. Hyperswitch retries anything else: 16 retries over about 24 hours.
  3. Dedupe on event_id. Retries can deliver the same event twice; acknowledge a duplicate without re-applying it.
  4. Don't assume order. For payments, compare content.object.updated with the stored value and apply only newer state.
  5. 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →