invoicepdfs-com Webhooks API

openapi: 3.2.0
info:
  title: Invoicepdfs Com Webhooks API
  version: 0.3.0
  contact:
    name: InvoicePDFs
    url: https://invoicepdfs.com/
  license:
    name: MIT
  description: 'Operations tagged webhooks across 2 of this provider''s published API definitions: openapi.json, invoicepdfs-com-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Webhooks
paths:
  /api/v1/webhook-endpoints:
    get:
      tags:
      - Webhooks
      summary: List Webhook Endpoints
      description: Every webhook endpoint registered on the account, newest first.
      operationId: list_webhook_endpoints
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
    post:
      tags:
      - Webhooks
      summary: Create Webhook Endpoint
      description: 'Register a URL to receive events.


        The endpoint starts active and begins receiving the events you list.


        The response carries the signing secret, and is the only one that ever

        will — store it now. Reading or listing endpoints never returns it, and

        the only way to get another is `rotate_webhook_secret`, which stops this

        one working.'
      operationId: create_webhook_endpoint
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-endpoints/{endpoint_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook Endpoint
      description: One webhook endpoint by id.
      operationId: get_webhook_endpoint
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
    patch:
      tags:
      - Webhooks
      summary: Update Webhook Endpoint
      description: 'Change an endpoint''s URL, description, event list or active flag.


        Only the fields you send are changed. Setting `is_active` to false stops

        new deliveries while keeping the endpoint and its history, which is the

        reversible alternative to deleting it.'
      operationId: update_webhook_endpoint
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointPatchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook Endpoint
      description: 'Remove an endpoint and its delivery history.


        The endpoint''s delivery records are deleted with it, including any still

        waiting to be retried. To stop deliveries without losing the history, set

        `is_active` to false instead.'
      operationId: delete_webhook_endpoint
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleBoolResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret:
    post:
      tags:
      - Webhooks
      summary: Rotate Webhook Secret
      description: 'Issue a new signing secret and return it.


        This is the only response that contains the secret, so it is also how you

        obtain the first one after creating an endpoint. The previous secret stops

        being accepted immediately: signatures computed with it will not verify.'
      operationId: rotate_webhook_secret
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-endpoints/{endpoint_id}/test:
    post:
      tags:
      - Webhooks
      summary: Test Webhook Endpoint
      description: 'Send a test event to this endpoint.


        Delivers a `test` event immediately, so you can confirm the URL is

        reachable and your signature check works before real events depend on it.


        Returns straight away with the delivery in `pending`; follow it with

        `get_webhook_delivery` to see whether it arrived.'
      operationId: test_webhook_endpoint
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-deliveries:
    get:
      tags:
      - Webhooks
      summary: List Webhook Deliveries
      description: 'Every webhook delivery attempt on the account, newest first.


        One row per attempt to POST an event to one of your endpoints, with the

        HTTP status and attempt count. For emails sent to your customers, see

        `get_delivery`.'
      operationId: list_webhook_deliveries
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveriesListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-deliveries/{delivery_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook Delivery
      description: 'One webhook delivery by id — an HTTP POST to one of your endpoints.


        Not to be confused with `get_delivery`, which is an email sent to a

        customer.'
      operationId: get_webhook_delivery
      security:
      - HTTPBearer: []
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          title: Delivery Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/webhook-deliveries/{delivery_id}/retry:
    post:
      tags:
      - Webhooks
      summary: Retry Webhook Delivery
      description: 'Send a failed or pending webhook delivery again, immediately.


        Resets the attempt counter on the same delivery and dispatches it without

        waiting for the retry schedule. Failed deliveries are already retried

        automatically with backoff, so this is for after those are exhausted — or

        to send a delivery created by `test_webhook_endpoint`.


        Refused with 409 in any other status. To re-send an email, use

        `retry_delivery`.'
      operationId: retry_webhook_delivery
      security:
      - HTTPBearer: []
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          title: Delivery Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
components:
  schemas:
    WebhookEndpointCreatedOut:
      properties:
        id:
          type: string
          title: Id
        url:
          type: string
          title: Url
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        events:
          items:
            type: string
          type: array
          title: Events
        is_active:
          type: boolean
          title: Is Active
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
        secret:
          type: string
          title: Secret
      type: object
      required:
      - id
      - url
      - events
      - is_active
      - created_at
      - updated_at
      - secret
      title: WebhookEndpointCreatedOut
      description: 'A newly created endpoint, including its signing secret.


        The only time the secret is returned. Store it now: reading or listing

        endpoints never includes it, and the only way to obtain another is to

        rotate, which invalidates this one.'
    WebhookDeliveryOut:
      properties:
        id:
          type: string
          title: Id
        endpoint_id:
          type: string
          title: Endpoint Id
        event_id:
          type: string
          title: Event Id
        event_type:
          type: string
          title: Event Type
        status:
          $ref: '#/components/schemas/WebhookDeliveryStatus'
        http_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Http Status
        attempts:
          type: integer
          title: Attempts
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        created_at:
          type: string
          title: Created At
        delivered_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivered At
      type: object
      required:
      - id
      - endpoint_id
      - event_id
      - event_type
      - status
      - attempts
      - created_at
      title: WebhookDeliveryOut
    WebhookDeliveryStatus:
      type: string
      enum:
      - pending
      - retrying
      - delivered
      - failed
      title: WebhookDeliveryStatus
    WebhookDeliveryResponse:
      properties:
        data:
          $ref: '#/components/schemas/WebhookDeliveryOut'
      type: object
      required:
      - data
      title: WebhookDeliveryResponse
    CursorPagination:
      properties:
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      title: CursorPagination
    WebhookEndpointResponse:
      properties:
        data:
          $ref: '#/components/schemas/WebhookEndpointOut'
      type: object
      required:
      - data
      title: WebhookEndpointResponse
    WebhookEndpointsListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WebhookEndpointOut'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      type: object
      required:
      - data
      title: WebhookEndpointsListResponse
    WebhookDeliveriesListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WebhookDeliveryOut'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      type: object
      required:
      - data
      title: WebhookDeliveriesListResponse
    WebhookEndpointCreateRequest:
      properties:
        url:
          type: string
          title: Url
          examples:
          - https://example.com/webhooks
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          examples:
          - Production webhook
        events:
          items:
            type: string
          type: array
          title: Events
          examples:
          - - invoice.created
            - invoice.paid
      type: object
      required:
      - url
      - events
      title: WebhookEndpointCreateRequest
    WebhookSecretResponse:
      properties:
        data:
          additionalProperties: true
          type: object
          title: Data
      type: object
      required:
      - data
      title: WebhookSecretResponse
    SimpleBoolResponse:
      properties:
        data:
          additionalProperties:
            type: boolean
          type: object
          title: Data
      type: object
      required:
      - data
      title: SimpleBoolResponse
      description: 'Generic boolean response envelope.


        Example:

        {"data": {"deleted": true}}'
    ApiErrorResponse:
      type: object
      title: ApiErrorResponse
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
              example: 422
              description: HTTP status, mirroring the response status line.
            code:
              type: string
              example: unprocessable_entity
            message:
              type: string
              example: Request validation failed
            request_id:
              type: string
              nullable: true
              description: Trace id for this request; also returned as X-Trace-Id.
            details:
              type: object
              nullable: true
              description: Error-specific context. Validation failures carry `fields`.
          required:
          - status
          - code
          - message
      required:
      - error
    WebhookEndpointPatchRequest:
      properties:
        url:
          type: string
          title: Url
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        events:
          items:
            type: string
          type: array
          title: Events
        is_active:
          type: boolean
          title: Is Active
      type: object
      title: WebhookEndpointPatchRequest
    WebhookEndpointOut:
      properties:
        id:
          type: string
          title: Id
        url:
          type: string
          title: Url
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        events:
          items:
            type: string
          type: array
          title: Events
        is_active:
          type: boolean
          title: Is Active
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
      - id
      - url
      - events
      - is_active
      - created_at
      - updated_at
      title: WebhookEndpointOut
    WebhookEndpointCreatedResponse:
      properties:
        data:
          $ref: '#/components/schemas/WebhookEndpointCreatedOut'
      type: object
      required:
      - data
      title: WebhookEndpointCreatedResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- invoicepdfs-com-openapi.json
x-internal-tags:
- auth
- jobs
- logs