Gareth Wilson Gareth Wilson

Guide to Hyperswitch Webhooks: Features and Best Practices

Published


Hyperswitch is Juspay's open-source payments switch: a single API in front of many payment processors, with routing, retries and a vault, that you can self-host or use as a hosted service. Since a payment can move between processors and states without your server making a call, Hyperswitch's outgoing webhooks are how your order, billing and payout systems learn the result of each payment, refund, dispute, mandate and payout.

This guide covers the outgoing event list, how a delivery is keyed to a business profile, verifying the SHA-512 signature, and coping with Hyperswitch's duplicate and out-of-order deliveries.

What are Hyperswitch webhooks?

Hyperswitch's webhook documentation describes two directions. Incoming webhooks are callbacks from connectors (Stripe, Adyen and the other processors) into Hyperswitch, which Hyperswitch verifies itself. Outgoing webhooks are the ones Hyperswitch sends to you, and they're the subject of this guide.

Outgoing webhooks are configured per business profile and per mode. Each profile in test or live mode has one endpoint URL and receives every event type; there's no per-event selection. Each delivery is a JSON POST with an event_id, an event_type and a content object holding the affected resource.

Signing depends on the profile. If you set a payment_response_hash_key, Hyperswitch adds X-Webhook-Signature-512, a hex HMAC-SHA512 of the body. If you don't, requests arrive unsigned.

Hyperswitch webhook features

FeatureDetails
ConfigurationControl Center: Developers > Payment Settings > Payment Behaviour
ScopeOne URL per business profile and mode, all event types
Signaturehex HMAC-SHA512
Signature headerx-webhook-signature-512
Signed contentThe raw request body
KeyThe profile's payment_response_hash_key. Unsigned if unset
BodyJSON
Event routingBody field event_type
Retries16 over roughly 24 hours
OrderingNot guaranteed
Live modeURL must be allowlisted by the Hyperswitch team

Events and payloads

Groupevent_typeCommon use
Paymentpayment_succeededFulfil the order
payment_failedNotify the customer, offer retry
payment_processingMark the order pending
payment_cancelled, payment_cancelled_post_captureRelease stock
payment_authorized, payment_partially_authorizedManual-capture flows
payment_capturedFunds captured
payment_expiredExpire the order
action_requiredCustomer must complete an action (for example 3DS)
Refundrefund_succeeded, refund_failed, refund_reviewUpdate refund state
Disputedispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lostEvidence workflow
Mandatemandate_active, mandate_revokedRecurring-payment consent
Payoutpayout_success, payout_failed, payout_initiated, payout_processing, payout_cancelled, payout_expired, payout_reversed, payout_not_permittedPayout state
Otherinvoice_paid, surcharge_payment_succeeded, surcharge_refund_succeededBilling and surcharge

Hyperswitch lists these wire values without descriptions, so the use column above is a guide to where each fits, not a definition from the docs.

Event Payload Structure

FieldRequiredNotes
merchant_idYes
event_idYesUnique per event; use it to dedupe
event_typeYesOne of the values above
contentYes{ type, object }
timestampNo
processor_merchant_idNoNullable

content.type is one of payment_details, refund_details, dispute_details, mandate_details, payout_details or subscription_details, and tells you the shape of content.object. It's coarser than event_type: every payment event carries payment_details, for example.

Hyperswitch publishes no example body for any event. The field list comes from the docs, and the resource shapes follow its v1 API schema, so capture a real test delivery before you write parsing code.

Setting up Hyperswitch webhooks

Prerequisites

  • A Hyperswitch account with access to the business profile you'll use
  • A public HTTPS endpoint that accepts POST

How Do I Get the Signing Secret?

Signing uses the business profile's payment_response_hash_key.

  1. Select the business profile in the Hyperswitch Control Center.
  2. Set payment_response_hash_key on the profile and store it securely.
  3. Put the same value in WEBHOOK_SECRET. The code uses its UTF-8 bytes as the HMAC key.

The docs don't say whether Hyperswitch generates the key or you choose it. Until a key is set, deliveries have no X-Webhook-Signature-512 header.

How Do I Register the Endpoint?

  1. In the Control Center, select the business profile and mode the endpoint is for.
  2. Go to Developers > Payment Settings > Payment Behaviour.
  3. Add the endpoint URL and save.
  4. For live mode, ask the Hyperswitch team to allowlist the URL. Live deliveries won't reach an endpoint that hasn't been approved.
  5. Make a test payment and confirm your endpoint returns a 2xx.

If you run several profiles (for example one per brand or region), each needs its own URL and may have its own key. Test and live are configured separately even for the same profile.

Connector Callbacks (Not Covered)

The same Hyperswitch guide explains how to register Hyperswitch's callback URL (POST /account/{account_id}/webhooks/{merchant_connector_id}) on each processor's dashboard. Those requests flow from the processor to Hyperswitch, are signed by the processor, and don't involve your endpoint or a Hookdeck Hyperswitch source.

Test a delivery

Start a local receiver and forward requests with the Hookdeck CLI:

npx hookdeck-cli listen 3000 hyperswitch --path /webhooks/hyperswitch

Use the CLI's URL on a test-mode profile and run a test payment. Since there's no published sample, that first delivery is your reference for the content.object fields.

Securing Hyperswitch webhooks

Compute HMAC-SHA512 over the raw body with the payment_response_hash_key as UTF-8 bytes, hex-encode it, and compare it with X-Webhook-Signature-512 in constant time. The header is the bare 128-character digest, with no sha512= prefix. Hyperswitch's verification section has the details.

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-webhook-signature-512'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha512', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{128}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The handler skips repeated event_id values and ignores payment updates that are older than the state you already hold, using content.object.updated.

const express = require('express');

function createHyperswitchApp({ seenEvent, latestPaymentUpdate, apply }) {
  const app = express();
  app.post('/webhooks/hyperswitch', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    let parsed;
    try {
      parsed = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
    const { event_id, event_type, content } = parsed;
    if (!event_id || typeof event_type !== 'string' || !content || typeof content !== 'object' || !content.object || typeof content.object !== 'object') {
      return res.sendStatus(400);
    }
    try {
      if (await seenEvent(event_id)) return res.sendStatus(200);
      if (content && content.type === 'payment_details') {
        const payment = content.object;
        const known = await latestPaymentUpdate(payment.payment_id);
        if (known && new Date(payment.updated) < new Date(known)) return res.sendStatus(200);
      }
      switch (event_type) {
        case 'payment_succeeded':
        case 'payment_captured':
        case 'payment_failed':
        case 'action_required':
        case 'refund_succeeded':
        case 'refund_failed':
        case 'dispute_opened':
        case 'payout_success':
        case 'payout_failed':
          await apply(event_type, content.object);
          break;
        default:
          console.log('Unhandled Hyperswitch event', event_type);
      }
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

The optional body timestamp isn't part of any documented freshness check, and only the body is signed, so a replayed request verifies. event_id deduplication is your defence.

A Hookdeck source of the Hyperswitch type verifies X-Webhook-Signature-512 as a hex SHA-512 HMAC of the raw body. It returns 200 to Hyperswitch either way and marks a mismatch as failed verification, which stops that request from being delivered onwards. Hookdeck applies no timestamp window.

Set payment_response_hash_key on the Hyperswitch business profile and use it as the verification secret. Without it, deliveries are unsigned and fail verification. Live-mode webhook URLs must be allowlisted by Hyperswitch.

If a profile has no key and you intend to keep it that way, leave verification off on the source rather than pasting a secret Hyperswitch isn't using.

Make Hyperswitch webhooks production-ready. Hookdeck Event Gateway verifies every Hyperswitch delivery, drops duplicate event_id values, and lets you replay payment and payout events after an outage.

Hyperswitch webhook limitations and pain points

Out-of-order delivery

The Problem: An order flips back from paid to processing, or a payout shows as initiated after it succeeded.

Why It Happens: Hyperswitch says outright that delivery order may not match event order, and retries of an earlier event can land after a later one.

Workarounds:

  • For payments, compare content.object.updated with the last update you stored.
  • Treat terminal states as final, or fetch the current state from the Hyperswitch API before acting.

How Hookdeck Can Help: Hookdeck's event log shows the order in which each delivery arrived and its full body, which helps when debugging a state that went backwards.

Duplicates

The Problem: A refund is recorded twice, or a fulfilment job runs twice.

Why It Happens: Hyperswitch documents that the same event can be delivered more than once.

Workarounds:

  • Store event_id with the change it caused, in one transaction.

How Hookdeck Can Help: Hookdeck deduplication can filter repeated event_id values before they reach your service.

Unsigned unless you set a key

The Problem: Anyone who learns the URL can post a fake payment_succeeded.

Why It Happens: Signing is tied to payment_response_hash_key, and a profile without one sends no signature header.

Workarounds:

  • Set a key on every profile that sends webhooks, test and live.
  • Reject requests without X-Webhook-Signature-512 once the key is set.

How Hookdeck Can Help: With verification enabled on the source, unsigned and forged requests are logged as failed and never forwarded.

No samples, descriptions or IP list

The Problem: It's hard to write and test a parser, and the endpoint can't be locked down by network.

Why It Happens: The docs list the 33 event_type values with no description and no example body, and publish no egress IP range. Live URLs are allowlisted by Hyperswitch, but that's an approval of your URL, not a list of Hyperswitch's addresses.

Workarounds:

  • Trigger each event you rely on in test mode and save the bodies as fixtures.
  • Rely on signature verification for authenticity.

How Hookdeck Can Help: Every delivery Hookdeck receives is stored with headers and body, which gives you real fixtures for each event type.

One endpoint for every event

The Problem: Payout, dispute and payment handlers all share one URL and one deployment.

Why It Happens: Each profile and mode has a single URL and no per-event filter.

Workarounds:

  • Route on event_type inside a thin receiver that hands work to separate queues.

How Hookdeck Can Help: Connection filters on event_type send payments, disputes and payouts to different destinations from one Hookdeck source.

Best practices

Keep each profile's key separate

Store one secret per business profile and mode, and point each at its own Hookdeck source or receiver path. A delivery verified with the wrong profile's key fails, which is easier to diagnose when each source has a single key.

Use the retry window, but don't depend on it

RetryDelay
1st1 minute after the original attempt
2nd and 3rd5 minutes
4th to 8th10 minutes
9th to 13th1 hour
14th to 16th6 hours

Return a 2xx as soon as the event is stored. The docs state no timeout, so do fulfilment and ledger work in a background job, as the asynchronous processing guide describes.

Make every handler idempotent

Retries, duplicates and replays all reuse event_id. Record it with the side effect, following the approach in our webhook idempotency guide.

Treat unknown event types as normal

The documented list of 33 values isn't presented as complete, and a profile receives every type. Log anything unhandled and return 2xx, so an unfamiliar value doesn't cause 16 retries.

Conclusion

Hyperswitch's outgoing webhooks are signed simply once a profile key exists, and the retry schedule is generous. Ordering is where the work lies: duplicates and out-of-order arrivals are both documented, so keep state transitions monotonic and check updated timestamps on payments.

Hookdeck Event Gateway adds deduplication, per-event routing and replay on top of a single Hyperswitch endpoint.

Get started with Hookdeck for free and handle Hyperswitch webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.