​
Developer playbooks

These runbooks are the shortest path from “something looks wrong” to a concrete next action. They are public, merchant-safe playbooks for the supported Hilt contract.

​
1. Launch a webhook endpoint safely

Use this when a backend is moving from polling-first integration to native Hilt events.

​
Goal

Receive signed events for payments, receipts, memberships, delivery failures, and support changes without guessing whether the consumer is really ready.

​
Sequence

  1. create the webhook endpoint in the dashboard or with POST /v1/webhooks/endpoints
  2. subscribe only to the event types you are ready to process
  3. if the consumer is product-specific, filter the endpoint to the relevant product ids
  4. send a signed test event
  5. verify the signature against the raw body
  6. make sure your consumer is idempotent on event.id
  7. complete one tiny live payment and confirm the real payment.confirmed event lands

​
Useful routes

POST /v1/webhooks/endpoints
POST /v1/webhooks/endpoints/{endpoint_id}/test
GET  /v1/webhooks/deliveries
GET  /v1/webhooks/timeline
POST /v1/webhooks/deliveries/{delivery_id}/replay

​
Good outcome

  • test event returns 2xx
  • delivery log shows a clean first success
  • one real payment reaches payment.confirmed
  • your consumer unlocks access only after Hilt confirms the payment

​
2. Recover a failed delivery

Use this when payment succeeded but Telegram, Discord, or another delivery path did not complete cleanly.

​
Sequence

  1. inspect the membership by membership_id
  2. load provider diagnostics
  3. if the problem is transient, retry delivery
  4. if the issue is still unclear, open or reuse the linked delivery support ticket
  5. if proof is part of the recovery conversation, send the receipt proof link directly

​
Useful routes

GET  /v1/memberships/{membership_id}
GET  /v1/memberships/{membership_id}/delivery-diagnostics
POST /v1/memberships/{membership_id}/retry-delivery
POST /v1/memberships/{membership_id}/delivery-support-ticket
POST /v1/receipt/{receipt_id}/send-proof

​
Good outcome

  • provider state is visible before you retry
  • the retry result stays tied to the same membership trail
  • support history stays attached to the recovery path

​
3. Prove a payment and send buyer-safe proof

Use this when a buyer or operator needs verifiable proof instead of a screenshot.

​
Sequence

  1. list or search receipts
  2. load the exact receipt
  3. open the public proof page if a human needs to inspect it
  4. send the proof link or PDF directly when support needs a clean buyer-facing artifact

​
Useful routes

GET  /v1/receipts
GET  /v1/receipt/{receipt_id}
GET  /v1/receipt/{receipt_id}/public
GET  /v1/receipt/{receipt_id}/pdf
POST /v1/receipt/{receipt_id}/send-proof

​
Good outcome

  • the operator sees the same payment trail as the merchant
  • the buyer gets a stable proof URL and PDF
  • the support action is tied to the receipt instead of separate email history

​
4. Recover a manual recurring member

Hilt is manual-renewal-first right now. Use this when a buyer needs the next approval path for the next period.

​
Sequence

  1. read renewal intelligence for the cohort view
  2. load the member reactivation detail
  3. choose the correct buyer-safe link:
    • renewal_url for the ordinary next cycle
    • reactivation_url when support needs the direct restore path
  4. keep the membership and support trail attached to that recovery step

​
Useful routes

GET /v1/memberships/renewal-intelligence
GET /v1/memberships/{membership_id}/reactivation

​
Good outcome

  • the buyer gets the right next action quickly
  • the merchant sees grace, expiry, and reminder timing clearly
  • support does not need to explain recurring operations from scratch

​
5. Validate an integration before live traffic

Hilt now has a narrow sandbox v1 for contract testing. It simulates Hilt lifecycle objects and signed webhooks, but it does not pretend to be a separate Solana settlement rail.

​
Use the sandbox for

  • webhook consumer testing
  • SDK and Postman flows
  • receipt and membership object-shape validation
  • delivery-failure and recurring-grace run-throughs

​
Use a tiny live payment for

  • final end-to-end launch validation
  • wallet flow
  • chain confirmation
  • real merchant payout path

​
Useful routes

GET  /v1/testing/scenarios
POST /v1/testing/sessions
GET  /v1/testing/sessions
GET  /v1/testing/sessions/{session_id}

​
Good outcome

  • your webhook consumer accepts livemode=false test traffic correctly
  • you can replay the same representative Hilt object flow safely
  • one tiny live payment is the last step, not the first step