Hilt Webhooks

asyncapi: 3.0.0
info:
  title: Hilt Webhooks
  version: '2026-05-04'
  description: 'Hilt webhook events delivered by HTTPS POST to merchant endpoints. GENERATED by API Evangelist (method:
    generated) from the provider''s documented webhook catalogue at https://docs.hilt.so/developers/webhooks, the
    signature and retry rules on that page, and the two example payloads Hilt publishes in github.com/Hiltpay/hilt-developer-assets/examples/webhooks.
    Hilt publishes no AsyncAPI of its own; nothing here is invented beyond that documentation.'
  contact:
    name: Hilt
    url: https://www.hilt.so
    email: support@hilt.so
  x-generated: '2026-09-19'
  x-method: generated
  x-source: https://docs.hilt.so/developers/webhooks
externalDocs:
  url: https://docs.hilt.so/developers/webhooks
servers:
  merchant-endpoint:
    host: '{merchant-host}'
    protocol: https
    description: 'The merchant-registered endpoint (POST /v1/webhooks/endpoints, operationId create_webhook_endpoint_v1_webhooks_endpoints_post,
      or POST /v1/access/webhooks). Hilt POSTs each event; only a 2xx counts as delivered. Retry schedule: immediate,
      30 s, 2 min, 10 min, 30 min, 2 h; then dead_letter (replayable via replay_owned_webhook_delivery_v1_webhooks_deliveries__delivery_id__replay_post).'
    variables:
      merchant-host:
        description: merchant-controlled host
channels:
  payment_confirmed:
    address: payment.confirmed
    description: The payment is final in Hilt and it is safe to unlock access
    messages:
      payment_confirmed:
        $ref: '#/components/messages/payment_confirmed'
  payment_failed:
    address: payment.failed
    description: The payment did not complete successfully
    messages:
      payment_failed:
        $ref: '#/components/messages/payment_failed'
  receipt_created:
    address: receipt.created
    description: Proof is available and a receipt verify URL can be used
    messages:
      receipt_created:
        $ref: '#/components/messages/receipt_created'
  membership_activated:
    address: membership.activated
    description: A membership or access record is active
    messages:
      membership_activated:
        $ref: '#/components/messages/membership_activated'
  membership_renewed:
    address: membership.renewed
    description: A renewal or extension was applied
    messages:
      membership_renewed:
        $ref: '#/components/messages/membership_renewed'
  membership_entered_grace:
    address: membership.entered_grace
    description: The membership moved into grace instead of remaining fully active
    messages:
      membership_entered_grace:
        $ref: '#/components/messages/membership_entered_grace'
  membership_expired:
    address: membership.expired
    description: Access has ended and downstream systems should treat it as inactive
    messages:
      membership_expired:
        $ref: '#/components/messages/membership_expired'
  membership_reapproval_required:
    address: membership.reapproval_required
    description: A recurring membership needs operator or buyer review
    messages:
      membership_reapproval_required:
        $ref: '#/components/messages/membership_reapproval_required'
  delivery_failed:
    address: delivery.failed
    description: A Telegram, Discord, redirect, or post-payment delivery step failed
    messages:
      delivery_failed:
        $ref: '#/components/messages/delivery_failed'
  support_ticket_created:
    address: support.ticket.created
    description: A new support issue was opened inside the Hilt payment trail
    messages:
      support_ticket_created:
        $ref: '#/components/messages/support_ticket_created'
operations:
  receive_payment_confirmed:
    action: receive
    channel:
      $ref: '#/channels/payment_confirmed'
    summary: The payment is final in Hilt and it is safe to unlock access
  receive_payment_failed:
    action: receive
    channel:
      $ref: '#/channels/payment_failed'
    summary: The payment did not complete successfully
  receive_receipt_created:
    action: receive
    channel:
      $ref: '#/channels/receipt_created'
    summary: Proof is available and a receipt verify URL can be used
  receive_membership_activated:
    action: receive
    channel:
      $ref: '#/channels/membership_activated'
    summary: A membership or access record is active
  receive_membership_renewed:
    action: receive
    channel:
      $ref: '#/channels/membership_renewed'
    summary: A renewal or extension was applied
  receive_membership_entered_grace:
    action: receive
    channel:
      $ref: '#/channels/membership_entered_grace'
    summary: The membership moved into grace instead of remaining fully active
  receive_membership_expired:
    action: receive
    channel:
      $ref: '#/channels/membership_expired'
    summary: Access has ended and downstream systems should treat it as inactive
  receive_membership_reapproval_required:
    action: receive
    channel:
      $ref: '#/channels/membership_reapproval_required'
    summary: A recurring membership needs operator or buyer review
  receive_delivery_failed:
    action: receive
    channel:
      $ref: '#/channels/delivery_failed'
    summary: A Telegram, Discord, redirect, or post-payment delivery step failed
  receive_support_ticket_created:
    action: receive
    channel:
      $ref: '#/channels/support_ticket_created'
    summary: A new support issue was opened inside the Hilt payment trail
components:
  messages:
    payment_confirmed:
      name: payment.confirmed
      title: payment.confirmed
      summary: The payment is final in Hilt and it is safe to unlock access
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
      examples:
      - name: payment.confirmed (provider example)
        payload:
          id: 1886194f-0a41-4ca6-a62d-e7d7ee5db3a2
          type: payment.confirmed
          api_version: '2026-05-04'
          created_at: '2026-05-04T13:42:11Z'
          livemode: true
          data:
            payment:
              id: f0f4e620-1ca3-4fc8-b0ba-2d04342fe467
              status: CONFIRMED
              amount_minor_units: 29000000
              token_mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
              tx_signature: 5B7WmR...example
              confirmed_at: '2026-05-04T13:42:10Z'
              delivery_status: SENT
              product:
                id: ae9673c8-95db-4b39-bc2c-b5e6d5dfd9d3
                slug: telegram-pro
                title: Telegram Pro Membership
            membership:
              id: 0ce94832-4da4-4f47-a7df-9505817d7022
              status: ACTIVE
              platform: TELEGRAM
              current_period_end_at: '2026-06-03T13:42:10Z'
            receipt:
              id: 51b69947-0f0b-4a17-9170-229661000111
              verify_url: https://api.hilt.so/v1/receipt/51b69947-0f0b-4a17-9170-229661000111/verify
              schema_version: hilt-v1
    payment_failed:
      name: payment.failed
      title: payment.failed
      summary: The payment did not complete successfully
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    receipt_created:
      name: receipt.created
      title: receipt.created
      summary: Proof is available and a receipt verify URL can be used
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    membership_activated:
      name: membership.activated
      title: membership.activated
      summary: A membership or access record is active
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    membership_renewed:
      name: membership.renewed
      title: membership.renewed
      summary: A renewal or extension was applied
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    membership_entered_grace:
      name: membership.entered_grace
      title: membership.entered_grace
      summary: The membership moved into grace instead of remaining fully active
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    membership_expired:
      name: membership.expired
      title: membership.expired
      summary: Access has ended and downstream systems should treat it as inactive
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    membership_reapproval_required:
      name: membership.reapproval_required
      title: membership.reapproval_required
      summary: A recurring membership needs operator or buyer review
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
    delivery_failed:
      name: delivery.failed
      title: delivery.failed
      summary: A Telegram, Discord, redirect, or post-payment delivery step failed
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
      examples:
      - name: delivery.failed (provider example)
        payload:
          id: 2fe78f87-1157-4b57-a316-ae9a7731cfa0
          type: delivery.failed
          api_version: '2026-05-04'
          created_at: '2026-05-04T13:44:02Z'
          livemode: true
          data:
            payment:
              id: f0f4e620-1ca3-4fc8-b0ba-2d04342fe467
              status: CONFIRMED
              delivery_status: FAILED
              product:
                id: ae9673c8-95db-4b39-bc2c-b5e6d5dfd9d3
                slug: telegram-pro
                title: Telegram Pro Membership
            membership:
              id: 0ce94832-4da4-4f47-a7df-9505817d7022
              status: ACTIVE
              platform: TELEGRAM
              delivery_status: FAILED
            delivery:
              channel: TELEGRAM
              status: FAILED
              failure_code: invite_expired
              failure_message: Telegram invite expired before the buyer joined.
    support_ticket_created:
      name: support.ticket.created
      title: support.ticket.created
      summary: A new support issue was opened inside the Hilt payment trail
      contentType: application/json
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WebhookEnvelope'
  schemas:
    WebhookHeaders:
      type: object
      properties:
        X-Hilt-Signature:
          type: string
          description: t=<unix_timestamp>,v1=<hex_hmac_sha256>; HMAC-SHA256 over "<timestamp>.<raw_json_body>" with
            the endpoint signing secret. Verify with a timing-safe compare against the RAW body.
          examples:
          - t=1714830131,v1=5f1d...
      required:
      - X-Hilt-Signature
    WebhookEnvelope:
      type: object
      required:
      - id
      - type
      - api_version
      - created_at
      - livemode
      - data
      properties:
        id:
          type: string
          format: uuid
          description: Deduplicate by this id, not by payload order.
        type:
          type: string
          enum:
          - payment.confirmed
          - payment.failed
          - receipt.created
          - membership.activated
          - membership.renewed
          - membership.entered_grace
          - membership.expired
          - membership.reapproval_required
          - delivery.failed
          - support.ticket.created
        api_version:
          type: string
          description: Date-stamped webhook schema version (example 2026-05-04).
        created_at:
          type: string
          format: date-time
        livemode:
          type: boolean
        data:
          type: object
          description: Event-specific object. Payment-linked events include payment.id, payment.product.id, membership.id
            and receipt.id when applicable (see the provider example).
          additionalProperties: true
  securitySchemes:
    hiltSignature:
      type: symmetricEncryption
      description: HMAC-SHA256 signature in X-Hilt-Signature using the per-endpoint signing secret returned when
        the endpoint is created.
x-testing:
  send_test_event: POST /v1/webhooks/endpoints/{endpoint_id}/test with event_type (operationId test_webhook_endpoint_v1_webhooks_endpoints__endpoint_id__test_post);
    CLI hilt webhooks test ENDPOINT_ID --event payment.confirmed
  deliveries: GET /v1/webhooks/deliveries (status filter dead_letter), GET /v1/webhooks/timeline?payment_id=
  sdk: '@hiltpay/sdk src/webhooks.ts and hilt_sdk/webhooks.py verify + route helpers'
x-access-events:
  note: Hilt Pay API (/v1/access) subscribes webhooks via POST /v1/access/webhooks with subscribed_events such as
    access.entitlement.activated and payment.confirmed (SDK README example); the access.* event family is referenced
    in the SDK but not enumerated on the docs page, so it is not listed as a channel here.