> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumina-org.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook

> Register a URL to receive POST callbacks for the calling wallet's events. The response includes a 32-byte hex secret used by the sender for HMAC-SHA256 signing — STORE IT NOW, it is not returned again. Receivers verify with `X-Lumina-Signature` header (hex of HMAC-SHA256(body, secret)).



## OpenAPI

````yaml POST /api/v1/webhooks
openapi: 3.0.3
info:
  title: Lumina Protocol API
  version: 0.1.0
  description: >-
    Programmatic access to Lumina (Base mainnet 8453). Discover canonical
    contract addresses via GET /health.


    ## Authentication


    - Public endpoints (`/health`, `/products`, `/policies/...`) require no
    auth.

    - Authenticated endpoints under `/api/v1/*` (except `/api/v1/agent/onboard`)
    require an `x-api-key` header. Obtain one via `POST /api/v1/agent/onboard`
    (signed by your wallet) or have an admin call `POST /api/v1/keys/generate`.

    - Admin endpoints under `/api/v1/keys` require an `x-admin-token` header.


    ## Idempotency


    `POST /api/v1/policies` honours an optional `Idempotency-Key` header. A
    repeated call with the same key (per agent) returns the cached response.


    ## Numeric encoding


    All on-chain integer values (USDC base units, LUMINA wei, prices, etc.) are
    returned as decimal strings to avoid JavaScript Number precision loss.
  contact:
    url: https://www.lumina-org.com
  license:
    name: Proprietary
servers:
  - url: https://lumina-api-production-ac85.up.railway.app
    description: Production (Base mainnet 8453)
  - url: http://localhost:8080
    description: Local dev
security: []
tags:
  - name: discovery
    description: Service health & configuration discovery
  - name: products
    description: Insurance product catalogue and quotes
  - name: policies
    description: Buy and read insurance policies
  - name: redeem
    description: Verify and record bond redemptions
  - name: bonds
    description: List bonds (ERC-1155 epochs) for a wallet
  - name: marketplace
    description: 'Secondary marketplace: list / buy / browse bonds'
  - name: oracle
    description: Off-chain price oracle signer
  - name: keys
    description: 'Admin: API key issuance & revocation'
  - name: agent
    description: Self-service supervisor surface for agents/wallets
  - name: webhooks
    description: Subscribe to event push (HMAC-signed POST callbacks)
  - name: sandbox
    description: Public 'Try It' surface — pre-funded wallet, $1 cap
paths:
  /api/v1/webhooks:
    post:
      tags:
        - webhooks
      summary: Create a webhook subscription
      description: >-
        Register a URL to receive POST callbacks for the calling wallet's
        events. The response includes a 32-byte hex secret used by the sender
        for HMAC-SHA256 signing — STORE IT NOW, it is not returned again.
        Receivers verify with `X-Lumina-Signature` header (hex of
        HMAC-SHA256(body, secret)).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  example: https://my-bot.example.com/webhooks/lumina
                events:
                  oneOf:
                    - type: string
                      enum:
                        - '*'
                    - type: array
                      items:
                        type: string
                        enum:
                          - policy_purchased
                          - policy_triggered
                          - bond_minted
                          - bond_redeemed
                          - listing_created
                          - listing_purchased
                      minItems: 1
                  default: '*'
      responses:
        '201':
          description: Subscription created. The `secret` field is shown ONLY here.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  id:
                    type: integer
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      type: string
                  secret:
                    type: string
                    description: 32-byte hex (64 chars). Used to verify HMAC. Stored once.
                  warning:
                    type: string
        '400':
          description: Invalid url or events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, malformed, or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Authenticated but not allowed to access this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Duplicate URL for this wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Machine-readable error code (e.g. validation_error,
            unauthenticated).
          example: validation_error
        message:
          type: string
          description: Human-readable explanation.
        details:
          type: array
          description: >-
            Per-field validation issues (zod path + message). Only present for
            validation_error.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Issued via POST /api/v1/agent/onboard or POST /api/v1/keys/generate.
        Format: lk_<64-hex>.

````