Deploy Hyperswitch Webhooks

Deploy and Host self hosted Hyperswitch Webhooks (Open-Source Payment Switch with Signed Webhooks) on Railway

This template runs Hyperswitch on Railway: router, control center, Postgres and Redis. It covers both webhook directions, connector events coming in and signed events going out, so your backend gets verified payment status.

About Hosting Hyperswitch Webhooks open-source software on Railway (self hosted Hyperswitch webhooks template)

The data is yours: payments, profiles, connector keys and webhook settings live in the Postgres and Redis inside your own Railway project, so you can export or move them any time.

Why Deploy Hyperswitch Webhooks, the Stripe alternative on Railway (Railway Free Trial)

Stripe bundles webhooks into the processor, so you pay Stripe fees and accept Stripe-Signature semantics. Here you own the endpoint, the signing key and the event log, and pay only Railway hosting plus whatever the processor charges. Start on the $5 trial.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hyperswitch Webhooks on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for Hyperswitch Webhooks self hosting

Both webhook directions need a public HTTPS endpoint, so the choice is mostly about who runs TLS, Postgres and Redis.

Common Use Cases for hosted Hyperswitch Webhooks

• Fulfil only on confirmed money: mark an order paid when a verified payment_succeeded lands, not when the client says the card went through. Anything unverified stays pending.
• One handler, many connectors: normalise Stripe, Adyen and the rest behind a single event_type switch, so adding a processor doesn't mean a new endpoint, a new signature scheme and a new set of bugs.
• Refunds and disputes: react to refund_succeeded, dispute_opened and dispute_lost by updating ledgers and flagging orders for review, rather than waiting for a support ticket.
• Duplicate-safe processing: store event_id before doing work, so a retried delivery, or your own retry, doesn't ship the order twice or double-credit a wallet.
• Reconcile what never arrived: this template doesn't run the scheduler, so pair webhooks with payment sync as a fallback for deliveries that failed silently.

Dependencies for Hyperswitch Webhooks Docker hosted on Railway

You need the router image ghcr.io/onepush-dev/hyperswitch-router:v1.128.0 on port 8080, control-center juspaydotin/hyperswitch-control-center:v1.38.10 on port 9000, Postgres 18 and Redis 8.2.

Deployment Dependencies for Managed Hyperswitch Webhooks Service (Payment Webhooks)

Generated: ROUTER__SECRETS__ADMIN_API_KEY (32 chars), JWT_SECRET (48), and MASTER_ENC_KEY, HASH_KEY and ENCRYPTION_KEY as 64-character hex. Back up MASTER_ENC_KEY, or stored data becomes unreadable. There's no payment_response_hash_key generated for you.

Implementation Details for Hyperswitch Webhooks (Using Hyperswitch official docker image)

Set payment_response_hash_key on the business profile and register the connector webhook with POST /account/{account_id}/webhooks/{merchant_connector_id}. No scheduler here, so reconcile with payment sync.

How does Hyperswitch Webhooks compare against other ways to receive payment status events

Each option pushes payment status events to your backend. What differs is who normalises them, who signs them, and who owns retries.

Hyperswitch vs Stripe (Stripe Alternative)

• Event shape: one normalised envelope from many connectors, not Stripe objects.
• Two directions: Stripe only pushes; Hyperswitch also takes inbound connector webhooks.
• Signature: Stripe-Signature per endpoint versus HMAC-SHA512 in X-Webhook-Signature-512.
• Where Stripe wins: managed retries; this template skips the scheduler.

Hyperswitch vs Adyen (Adyen Alternative)

• Normalisation: Adyen signs its own notification shape; Hyperswitch maps them to payment_succeeded, refunds and disputes.
• Signing: Adyen hashes notification fields; Hyperswitch hashes the raw body, so keep bytes intact.
• Where Adyen wins: enterprise support and one contract if you're already on Adyen.

Hyperswitch vs Spreedly (Spreedly Alternative)

• Openness: Spreedly is closed orchestration; Hyperswitch is Apache-2.0, so you can read the webhook code.
• Hosting: Spreedly is SaaS only; here the router and control center run on your Railway project.
• Where Spreedly wins: no infrastructure to run, and a broader connector list in places.

Hyperswitch vs Primer (Primer Alternative)

• Workflows: Primer ships no-code orchestration; Hyperswitch uses config in the control center.
• Events: both normalise; Hyperswitch's v1 schema has 33 event types with event_id for dedupe.
• Where Primer wins: managed delivery and support without a scheduler to babysit.

How to use Hyperswitch Webhooks (the OSS payment switch)?

1. Put up a public HTTPS endpoint that accepts POST and returns 2xx.
2. Open the control center, pick your business profile and mode.
3. Developers > Payment Settings > Payment Behaviour, add the webhook URL, save.
4. Set payment_response_hash_key on that profile.
5. Make a test payment, then verify on raw bytes:

const expected = crypto.createHmac('sha512', hashKey).update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) res.sendStatus(401);

6. Store event_id before processing, return 2xx only after you accept it.
7. Register the connector webhook with the router as well.
8. Missed events? Payment sync is your fallback; no retry scheduler runs here.

How to self host Hyperswitch Webhooks on other VPS Services (Hyperswitch self hosting guide)

The same router and control center run fine on a plain VPS. You'll manage the database, Redis, TLS and process supervision yourself.

Clone the Repository

git clone https://github.com/juspay/hyperswitch
cd hyperswitch

Install Dependencies

Docker with Compose v2, plus Postgres 18 and Redis 8.2 (the compose file can run both).

Configure Environment Variables

Edit config/docker_compose.toml (or the matching ROUTER__ environment variables): set the admin API key, JWT secret, and the three 64-character hex keys. Point the control center's api_url at your router domain and ROUTER__USER__BASE_URL at the dashboard. Set payment_response_hash_key per business profile in the control center.

Start the Hyperswitch Webhooks Application

docker compose up -d

Put a reverse proxy in front so the router gets HTTPS on 8080 and the dashboard on 9000, then point connector webhooks and your merchant endpoint at those hostnames.

Railway handles Postgres and Redis wiring, migrations, HTTPS domains and health checks for you.

Official Pricing of Hyperswitch Webhooks (Hyperswitch pricing)

The software is free. What you pay for is infrastructure: about $15-30/mo on Railway at light use.

Hyperswitch Webhooks cloud vs self hosted comparison (Pricing, features, costs, and more)

The cloud option trades money and data residency for someone else running the scheduler and the queue. Self hosting keeps payment events and the hash key on infrastructure you control, but you own the retries too.

Monthly cost of self hosting Hyperswitch Webhooks on Railway

Expect about $15-30 a month for the router, control center, Postgres and Redis at light use, on top of the $5 trial credit. That is Railway's usage billing only. Connectors still charge their own processing fees, and there's no licence cost because Hyperswitch is Apache-2.0.

System Requirements for Hosting Hyperswitch Webhooks on a VPS

You need Docker, roughly 4 GB of RAM to run router, control center, Postgres and Redis together, and a public HTTPS domain the connectors and your own handler can reach. Persistent disk for Postgres and the router volume matters.

Frequently Asked Questions (FAQs)

Why doesn't my signature match?

You hashed a re-serialised body. HMAC-SHA512 covers the exact bytes, so read the raw request, sign it, and compare in constant time. Confirm the key is the profile's payment_response_hash_key.

Which events exist?

33 in the v1 schema, including payment_succeeded, payment_failed, refund_succeeded, dispute_opened and payout_failed. Filter on event_type.

Are webhooks retried here?

No. Upstream's scheduler does 16 retries over 24 hours, but this template doesn't run it, so failed deliveries aren't re-sent. Reconcile with payment sync.

How do I handle duplicates?

Deduplicate on event_id with a unique index or atomic insert before you change order state. Retries and re-deliveries both produce duplicates.

Do connectors point at my Hyperswitch URL?

Yes. Stripe and Adyen send to Hyperswitch, which verifies and maps the event. Register with POST /account/{account_id}/webhooks/{merchant_connector_id}. Connectors without webhook support need polling.

What if an event never arrives?

Call payment retrieve or sync, reconcile against your records, then run the same handler manually. Return 2xx fast and work after storing the event.