Skip to main content

Webhooks

Webhooks matter in Hilt because payments and subscriptions are asynchronous.

That does not mean every merchant needs to build against raw provider callbacks. The important split is:

  • Hilt receives provider webhooks and settles state internally
  • merchants consume payment, membership, receipt, and billing state from Hilt

The webhook model at launch​

There are two incoming webhook surfaces in the Hilt stack today:

  1. Helius -> Hilt for on-chain payment settlement
  2. Stripe -> Hilt for Hilt’s own merchant subscription billing

There is not yet a public launch contract for merchant-defined outgoing webhooks from Hilt to your backend.

So the main merchant-facing integration pattern today is:

  1. publish a checkout template
  2. initiate payment from the hosted flow
  3. let Hilt settle the payment asynchronously
  4. inspect members and receipts in the app or through the API

If you need server-side reaction logic, use Hilt’s status routes rather than assuming you need the raw upstream webhook.

Helius payment webhook​

Endpoint:

POST https://api.hilt.so/v1/products/webhook/helius

What it does:

  • verifies the incoming HMAC signature
  • parses the enhanced transaction payload
  • extracts the HILT:{nonce} memo
  • finds the matching payment session
  • runs the same confirmation pipeline used by POST /v1/pay/confirm

Security details:

  • header: helius-signature
  • secret: helius_auth_secret
  • verification: HMAC SHA-256 over the raw request body

Important design detail:

  • checkout links can be dynamic
  • the webhook URL stays fixed
  • payment correlation happens by memo nonce, not by checkout URL

That is how Hilt safely tells simultaneous payments apart.

Stripe billing webhook​

Endpoint:

POST https://api.hilt.so/v1/billing/webhooks/stripe

What it does:

  • verifies the Stripe signature
  • records the webhook event idempotently
  • updates merchant billing state in Hilt

Security details:

  • header: Stripe-Signature
  • secret: stripe_webhook_secret
  • verification uses Stripe’s official webhook signature model

Events currently handled by Hilt:

  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.paid
  • invoice.payment_failed

Important note:

  • this webhook is for Hilt’s own merchant billing
  • it is not the buyer’s on-chain checkout settlement path

Merchant-consumable status routes today​

Live public integration routes include:

  • GET /v1/products/p/<slug>
  • POST /v1/products/p/<slug>/connect
  • POST /v1/pay/confirm
  • GET /v1/payments/<payment_id>
  • GET /v1/memberships
  • GET /v1/memberships/lookup

Platform-side confirmation also runs behind the scenes, but the public merchant contract is still the hosted checkout flow plus payment and membership status routes.

In the dashboard this workflow is presented as templates. In the API and CLI, the same merchant objects are called products.

If you need app-side automation today:

  • use the hosted checkout routes for buyer flow
  • use GET /v1/payments/{payment_id} for runtime status
  • use memberships and receipts for post-payment state
  • use support and billing routes for the merchant operating trail

This is the safest launch contract because it matches the live product and keeps your code independent from upstream provider quirks.

Retry and idempotency expectations​

Webhook providers may redeliver.

So you should assume:

  • Helius may retry the same transaction payload
  • Stripe may redeliver the same event
  • payment confirmation can be pending while the wallet transaction is already real

Hilt’s side already protects the core flows through:

  • webhook signature verification
  • payment correlation by memo nonce
  • duplicate-safe webhook event storage for Stripe
  • payment status polling through payment_id

Your side should still be careful to:

  • persist the original payment_id
  • persist the original tx_signature when you have it
  • treat repeated “confirmed” reads as normal
  • avoid asking buyers to sign again while a payment is merely pending

What merchants should not build yet​

At launch, do not assume Hilt has a public outgoing webhook system for:

  • payment completed callbacks to your backend
  • membership activated callbacks
  • receipt issued callbacks

If you need those behaviors today, build them around:

  • GET /v1/payments/{payment_id}
  • GET /v1/memberships
  • GET /v1/memberships/lookup
  • GET /v1/receipts

That keeps your automation inside the supported contract.

Where webhooks fit after payment​

If you want to understand how Hilt turns settlement into memberships, receipts, support, and billing state, continue with Members, Receipts, Support, and Billing.

Use the dashboard if you want:

  • the fastest launch path
  • built-in support context
  • member verification without extra code
  • renewal handling without building extra tooling around access state

If you need a deeper integration surface, start with the API Reference, Examples, and the post-payment guide.