LuckPanda Webhooks API

openapi: 3.2.0
info:
  title: Luckpanda App Webhooks API
  version: 1.0.0
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: openapi.yaml, luckpanda-app-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://luckpanda.app/api/v1
- url: http://127.0.0.1:8787/api/v1
  description: Local `wrangler dev`
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      operationId: listWebhookEndpoints
      description: Needs `agent.manage` (people with that permission). Keys cannot manage webhooks.
      responses:
        '200':
          description: Endpoints
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                  next_cursor:
                    type: 'null'
      summary: List webhook endpoints
      x-summary-source: derived
    post:
      tags:
      - Webhooks
      operationId: createWebhookEndpoint
      summary: Add an endpoint; the signing secret is in this answer only
      description: The URL must be public http(s) and resolve (private, loopback and metadata addresses are refused). At most 10 endpoints per business.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCommandResult'
        '403':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhooks/{endpointId}:
    get:
      tags:
      - Webhooks
      operationId: getWebhookEndpoint
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      responses:
        '200':
          description: The endpoint (never the secret)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/Problem'
      summary: Get webhook endpoint
      x-summary-source: derived
    patch:
      tags:
      - Webhooks
      operationId: updateWebhookEndpoint
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCommandResult'
      summary: Update webhook endpoint
      x-summary-source: derived
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhookEndpoint
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommandBase'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCommandResult'
      summary: Delete webhook endpoint
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhooks/{endpointId}/roll-secret:
    post:
      tags:
      - Webhooks
      operationId: rollWebhookSecret
      description: A new secret, in this answer only. Deliveries from now on are signed with it.
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommandBase'
      responses:
        '200':
          description: Rolled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCommandResult'
      summary: Roll webhook secret
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhooks/{endpointId}/test:
    post:
      tags:
      - Webhooks
      operationId: testWebhookEndpoint
      description: Sends a `webhook.test` event now and answers with the delivery.
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      responses:
        '201':
          description: The delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
      summary: Test webhook endpoint
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhooks/{endpointId}/deliveries:
    get:
      tags:
      - Webhooks
      operationId: listWebhookDeliveries
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      - name: state
        in: query
        schema:
          type: string
          enum:
          - pending
          - delivered
          - failed
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Latest first
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
                  next_cursor:
                    type: 'null'
      summary: List webhook deliveries
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhook-deliveries/{deliveryId}:
    get:
      tags:
      - Webhooks
      operationId: getWebhookDelivery
      parameters:
      - $ref: '#/components/parameters/DeliveryId'
      responses:
        '200':
          description: The delivery with its payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
      summary: Get webhook delivery
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhook-deliveries/{deliveryId}/resend:
    post:
      tags:
      - Webhooks
      operationId: resendWebhookDelivery
      description: Delivers the same event (same `LuckPanda-Delivery` id, new signature time) now.
      parameters:
      - $ref: '#/components/parameters/DeliveryId'
      responses:
        '200':
          description: The delivery after the attempt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
      summary: Resend webhook delivery
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /webhooks/{endpointId}/replay:
    post:
      tags:
      - Webhooks
      operationId: replayWebhookEvents
      x-mcp-tool: webhook_replay
      summary: Human-only (agent.manage).
      parameters:
      - $ref: '#/components/parameters/EndpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
components:
  schemas:
    IdempotencyKey:
      type: string
      minLength: 16
      maxLength: 128
      pattern: ^[A-Za-z0-9._:-]+$
    WebhookEventType:
      type: string
      enum:
      - document.issued
      - document.sent
      - document.cancelled
      - document.paid
      - payment.recorded
      - party.created
      - party.updated
    WebhookEndpointInput:
      allOf:
      - $ref: '#/components/schemas/CommandBase'
      - type: object
        properties:
          url:
            type: string
            format: uri
            maxLength: 500
          description:
            type: string
            maxLength: 200
          events:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/WebhookEventType'
              - const: '*'
            description: '["*"] = every event, including ones added later. Default ["*"].'
          active:
            type: boolean
    WebhookCommandResult:
      allOf:
      - $ref: '#/components/schemas/CommandResult'
      - type: object
        properties:
          resource:
            allOf:
            - $ref: '#/components/schemas/WebhookEndpoint'
            - type: object
              properties:
                secret:
                  type: string
                  pattern: ^whsec_
                  description: Only when this call created the endpoint or rolled its secret.
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: 'VALIDATION_FAILED (422) the body or a field is wrong; see field_errors.

            FORBIDDEN (401 no or revoked key, 403 missing permission or grant).

            NOT_FOUND (404).

            APPROVAL_REQUIRED (403) an agent (or any key over /mcp) tried to issue, send or pay; send proposal_only to propose instead.

            INTEGRATION_LIMIT (403) a server-integration key is outside its kinds, legal entities or largest total.

            PAYWALL (402) the business has not unlocked the outcome (issuing needs the Sales module); the body names the module.

            INVALID_STATE (409) the document is not in a state that allows this (e.g. issuing a cancelled document).

            STALE_VERSION (409) expected_version is behind; reload and retry.

            IDEMPOTENCY_MISMATCH (409) the idempotency_key was used with a different body.

            DUPLICATE_EXTERNAL_REF (409) a document of this kind already has this external_ref.

            COMPLIANCE_BLOCKED (409) a compliance rule blocks the change (e.g. cancelling a document with an active e-invoice IRN).

            ALLOCATION_EXCEEDS_AVAILABLE (409) a payment allocation is more than the receipt or the amount due allows.

            NOT_IMPLEMENTED (501) a path or option that is planned but not served.

            DELIVERY_FAILED (502, /invoices send step) the email provider refused the message.

            RATE_LIMITED (429).

            '
          enum:
          - VALIDATION_FAILED
          - FORBIDDEN
          - NOT_FOUND
          - APPROVAL_REQUIRED
          - INTEGRATION_LIMIT
          - PAYWALL
          - INVALID_STATE
          - STALE_VERSION
          - IDEMPOTENCY_MISMATCH
          - DUPLICATE_EXTERNAL_REF
          - COMPLIANCE_BLOCKED
          - ALLOCATION_EXCEEDS_AVAILABLE
          - CONFLICT
          - NOT_IMPLEMENTED
          - DELIVERY_FAILED
          - RATE_LIMITED
          - INTERNAL_ERROR
        message:
          type: string
        field_errors:
          type: array
          items:
            type: object
            required:
            - path
            - code
            properties:
              path:
                type: string
              code:
                type: string
        correlation_id:
          $ref: '#/components/schemas/Uuid'
    CommandResult:
      type: object
      required:
      - operation_id
      - status
      - correlation_id
      properties:
        operation_id:
          $ref: '#/components/schemas/Uuid'
        status:
          type: string
          enum:
          - succeeded
          - awaiting_approval
          - preview
        correlation_id:
          $ref: '#/components/schemas/Uuid'
        resource:
          type: object
          additionalProperties: true
        approval_request_id:
          $ref: '#/components/schemas/Uuid'
    ToolInput:
      type: object
      description: The input schema of the operation's `x-mcp-tool` (minus the ids the path supplies). See `architecture/mcp-tools.json`.
      required:
      - idempotency_key
      - correlation_id
      additionalProperties: true
    CommandBase:
      type: object
      required:
      - idempotency_key
      - correlation_id
      properties:
        idempotency_key:
          $ref: '#/components/schemas/IdempotencyKey'
        correlation_id:
          $ref: '#/components/schemas/Uuid'
        dry_run:
          type: boolean
          default: false
        proposal_only:
          type: boolean
          default: false
          description: Make it a proposal for a person to accept instead of acting.
        approval_request_id:
          $ref: '#/components/schemas/Uuid'
    Uuid:
      type: string
      format: uuid
    WebhookDelivery:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        event_type:
          type: string
        state:
          type: string
          enum:
          - pending
          - delivered
          - failed
        attempts:
          type: integer
          maximum: 8
        next_attempt_at:
          type: string
          format: date-time
        last_status_code:
          type:
          - integer
          - 'null'
        last_error:
          type:
          - string
          - 'null'
        last_attempt_at:
          type:
          - string
          - 'null'
          format: date-time
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        payload:
          type: string
          description: The exact JSON body that is signed (GET /webhook-deliveries/{deliveryId} only).
    WebhookEndpoint:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        url:
          type: string
        description:
          type:
          - string
          - 'null'
        events:
          type: array
          items:
            type: string
        active:
          type: boolean
        version:
          type: integer
        secret_hint:
          type: string
          description: Last 4 characters of the secret.
        pending:
          type: integer
        failed:
          type: integer
        last_delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    Problem:
      description: Typed RFC 7807 error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    CommandAccepted:
      description: 'Command result: succeeded, awaiting_approval (a proposal) or preview (dry_run)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandResult'
  parameters:
    EndpointId:
      name: endpointId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    DeliveryId:
      name: deliveryId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque API key, lpk_...
      description: Made in Workspace > Developers (agent or server-integration). Not a JWT.
x-refined-from:
- openapi.yaml
- luckpanda-app-openapi.yaml