NMI Webhook Subscriptions API

openapi: 3.2.0
info:
  title: Payments Sign-Up Webhook Subscriptions API
  description: Payments Sign-Up API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://api.nmipayments.com/license
servers:
- url: https://sandbox.signup.nmi.com/api/v1
  description: Sandbox
- url: https://secure.nmi.com/api/v5/signup
  description: Production
tags:
- name: Webhook Subscriptions
  description: Manage Webhook Subscriptions
paths:
  /subscriptions:
    get:
      tags:
      - Webhook Subscriptions
      security:
      - oauth:
        - subscriptions:read
      summary: List all Subscriptions
      description: 'This operation returns a list of subscriptions.


        **Required scope:** `subscriptions:read`'
      operationId: getSubscriptions
      parameters:
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: Number of subscriptions per page
        required: false
        schema:
          type: integer
          enum:
          - 10
          - 20
          - 50
          - 100
          default: 10
      responses:
        '200':
          description: Successful response example
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - subscriptions
                  properties:
                    subscriptions:
                      type: array
                      maxItems: 1000
                      items:
                        allOf:
                        - $ref: '#/components/schemas/subscription'
                - $ref: '#/components/schemas/pagination'
              examples:
                subscriptions:
                  summary: Success
                  description: A few subscriptions with different callback URLs
                  value:
                    subscriptions:
                    - id: sub_d83116a5970d8700
                      callback_url: https://your_registered_callback.com
                      events:
                      - application.updated.data.requested
                      - application.approved
                      - application.cancelled
                      - application.declined
                      - application.merchant.boarded
                      status: active
                      created_at: '2025-02-25T18:07:23+00:00'
                      updated_at: '2025-02-25T18:08:00+00:00'
                    - id: sub_482385311458f55e
                      callback_url: https://your_callback_url.com
                      events:
                      - application.updated.data.requested
                      - application.approved
                      - application.cancelled
                      - application.declined
                      - application.merchant.boarded
                      status: active
                      created_at: '2025-02-21T19:40:51+00:00'
                      updated_at: '2025-02-24T20:20:33+00:00'
                    current_page: 1
                    per_page: 10
                    last_page: 1
                    total: 2
        '422':
          $ref: '#/components/responses/validation-error-page-size'
    post:
      tags:
      - Webhook Subscriptions
      security:
      - oauth:
        - subscriptions:write
      summary: Create a Subscription
      description: 'Creates a new subscription based on the provided data.

        #### How signing requests work

        When setting up, it''s common to generate, store, and share a secret between your app and the app that wants to receive webhooks. The secret should be a random string, and how to create it is entirely up to you. The package will use the secret to sign a webhook call.

        By default, the package will add a header called ```Signature``` that will contain a signature the receiving app can use if the payload hasn''t been tampered with.


        **Required scope:** `subscriptions:write`'
      operationId: createSubscription
      parameters:
      - in: header
        name: Idempotency-Key
        description: Provide a random key (for example, UUID) to make the request idempotent
        schema:
          type: string
          minLength: 10
          maxLength: 100
        required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-subscription'
            examples:
              success:
                summary: Success
                description: Subscribe to events
                value:
                  callback_url: https://your_callback_url.com
                  secret: random_secret
                  events:
                  - application.updated.data.requested
                  - application.approved
                  - application.declined
                  - application.cancelled
                  - application.merchant.boarded
              invalid-url:
                summary: Invalid URL
                description: Subscribe with none responsive URL
                value:
                  callback_url: https://random_url_not_working.test.com
                  secret: random_secret
                  events:
                  - application.approved
        description: New subscription data
        required: true
      responses:
        '200':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
              examples:
                success:
                  summary: New subscription created
                  description: New subscription created
                  value:
                    id: sub_a32ab32dc3209320
                    callback_url: https://your_callback_url.com
                    events:
                    - application.updated.data.requested
                    - application.approved
                    - application.declined
                    - application.cancelled
                    - application.merchant.boarded
                    status: active
                    created_at: '2025-01-01T00:00:00Z'
                    updated_at: '2025-01-01T00:00:00Z'
        '400':
          description: Invalid Subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation-error'
              examples:
                invalid-url:
                  summary: Invalid URL
                  description: Error when invalid URL is provided.
                  value:
                    code: VALIDATION_ERROR
                    message: The current URL does not respond to our request. Please ensure that it's available to receive requests.
                    errors:
                    - The current URL does not respond to our request. Please ensure that it's available to receive requests.
                invalid-event:
                  summary: Invalid Event
                  description: Error when invalid event is provided.
                  value:
                    code: VALIDATION_ERROR
                    message: The selected events is invalid.
                    errors:
                    - The selected events is invalid.
  /subscriptions/{subscription}:
    get:
      tags:
      - Webhook Subscriptions
      security:
      - oauth:
        - subscriptions:read
      summary: Get Subscription Information
      description: 'Returns information about a given subscription


        **Required scope:** `subscriptions:read`'
      operationId: getSubscription
      parameters:
      - name: subscription
        in: path
        description: The ID of the subscription to retrieve
        required: true
        schema:
          $ref: '#/components/schemas/subscription-id'
      responses:
        '200':
          description: Subscription information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
              examples:
                success:
                  $ref: '#/components/examples/sample-subscription'
        '404':
          $ref: '#/components/responses/error-not-found'
    patch:
      tags:
      - Webhook Subscriptions
      security:
      - oauth:
        - subscriptions:write
      summary: Update a Subscription
      description: 'Updates an subscription


        **Required scope:** `subscriptions:write`'
      operationId: updateSubscription
      parameters:
      - name: Idempotency-Key
        in: header
        description: Provide a random key (for example, UUID) to make the request idempotent
        schema:
          type: string
          minLength: 10
          maxLength: 100
        required: false
      - name: subscription
        in: path
        description: The ID of the subscription to update
        required: true
        schema:
          $ref: '#/components/schemas/subscription-id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-subscription'
            examples:
              update-events:
                summary: Update Events
                description: Update the list of subscribed events
                value:
                  events:
                  - application.updated.data.requested
                  - application.approved
                  - application.declined
                  - application.cancelled
                  - application.merchant.boarded
              update-callback-url:
                summary: Update Callback URL
                description: Update subscription callback URL
                value:
                  callback_url: https://your_callback_url.com
        description: Update subscription payload
        required: true
      responses:
        '200':
          description: Subscription updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
              examples:
                update-events:
                  summary: Events Updated
                  $ref: '#/components/examples/sample-subscription'
                update-callback-url:
                  summary: Callback URL Updated
                  $ref: '#/components/examples/sample-subscription'
        '404':
          $ref: '#/components/responses/error-not-found'
    delete:
      tags:
      - Webhook Subscriptions
      security:
      - oauth:
        - subscriptions:write
      summary: Delete a Subscription
      description: 'Deletes a subscription


        **Required scope:** `subscriptions:write`'
      operationId: deleteSubscription
      parameters:
      - name: Idempotency-Key
        in: header
        description: Provide a random key (for example, UUID) to make the request idempotent
        schema:
          type: string
          minLength: 10
          maxLength: 100
        required: false
      - name: subscription
        in: path
        description: The ID of the subscription to update
        required: true
        schema:
          $ref: '#/components/schemas/subscription-id'
      responses:
        '200':
          description: Subscription Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: 'Success Code: DELETED'
                    maxLength: 100
                  message:
                    type: string
                    description: Success Message
                    maxLength: 10000
              examples:
                success:
                  summary: Subscription deleted
                  description: Subscription deleted
                  value:
                    code: DELETED
                    message: Webhook subscription deleted successfully
        '404':
          $ref: '#/components/responses/error-not-found'
components:
  schemas:
    application-created-at:
      type: string
      description: 'The date and time when the application was created.

        '
      format: date-time
      maxLength: 32
      example: '2025-01-01T00:00:00Z'
    subscription-status:
      type: string
      enum:
      - active
      - inactive
    subscription-callback-url:
      type: string
      description: The callback URL of the subscription.
      maxLength: 1024
    subscription-id:
      type: string
      description: The unique identifier of the subscription.
      pattern: ^sub_[a-f0-9]{16}$
      minLength: 20
      maxLength: 20
    create-subscription:
      type: object
      required:
      - callback_url
      - secret
      - events
      properties:
        callback_url:
          $ref: '#/components/schemas/subscription-callback-url'
        secret:
          $ref: '#/components/schemas/subscription-secret'
        events:
          $ref: '#/components/schemas/subscription-events'
    subscription:
      type: object
      description: 'Subscription object.

        '
      required:
      - id
      - status
      - events
      - created_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/subscription-id'
        callback_url:
          $ref: '#/components/schemas/subscription-callback-url'
        status:
          $ref: '#/components/schemas/subscription-status'
        events:
          $ref: '#/components/schemas/subscription-events'
        created_at:
          $ref: '#/components/schemas/application-created-at'
        updated_at:
          $ref: '#/components/schemas/application-updated-at'
    subscription-secret:
      type: string
      description: "The secret key is used to generate a secure signature with the **HMAC-SHA256** hashing algorithm, which is included \nin the webhook event `Signature` header.\n"
      minLength: 6
      maxLength: 64
    application-updated-at:
      type: string
      description: 'The date and time when the application was last updated.

        '
      format: date-time
      maxLength: 32
      example: '2025-01-01T00:00:00Z'
    pagination:
      type: object
      summary: Pagination information
      required:
      - current_page
      - last_page
      - per_page
      - total
      properties:
        current_page:
          type: integer
          description: The current page number
        last_page:
          type: integer
          description: The last page number
        per_page:
          type: integer
          enum:
          - 10
          - 20
          - 50
          - 100
          description: 'The number of items per page (allowed values: 10, 20, 50, 100)'
        total:
          type: integer
          description: The total number of items
    update-subscription:
      type: object
      description: Update an existing subscription.
      properties:
        callback_url:
          $ref: '#/components/schemas/subscription-callback-url'
        secret:
          $ref: '#/components/schemas/subscription-secret'
        events:
          $ref: '#/components/schemas/subscription-events'
    event-types:
      type: string
      enum:
      - application.updated.data.requested
      - application.approved
      - application.declined
      - application.cancelled
      - application.merchant.closed
      - application.merchant.boarded
      - merchant.chargeback.added
      - merchant.deposit.new
      - merchant.first-batch
      - merchant.processing.start
      - merchant.processing.stop
      - merchant.residuals.published
      - merchant.retrieval.added
      - merchant.statement.new
      example: application.merchant.boarded
    subscription-events:
      type: array
      description: Subscription events
      maxItems: 1000
      items:
        allOf:
        - $ref: '#/components/schemas/event-types'
    validation-error:
      type: object
      properties:
        code:
          type: string
          description: Error code
          maxLength: 1000
        message:
          type: string
          description: Error message
          maxLength: 1000
        errors:
          type: array
          maxItems: 10
          items:
            type: string
            description: The error message
            maxLength: 1000
  responses:
    error-not-found:
      description: Error response for resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                description: Error code
                maxLength: 100
              message:
                type: string
                description: Error message
                maxLength: 10000
          examples:
            not-found:
              summary: Resource Not Found
              description: The resource cannot be found
              value:
                code: NOT_FOUND
                message: Resource not found
    validation-error-page-size:
      description: Bad request (validation error) response for invalid page size
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                description: Error code
                maxLength: 1000
              message:
                type: string
                description: Error message
                maxLength: 1000
              errors:
                type: array
                maxItems: 1000
                items:
                  type: string
                  description: The error message
                  maxLength: 1000
          examples:
            standard:
              summary: Invalid Page Size
              description: This response is returned when the page size is invalid
              value:
                code: VALIDATION_ERROR
                message: The selected per page is invalid.
                errors:
                - The selected per page is invalid.
  examples:
    sample-subscription:
      summary: Success
      description: Subscription Information
      value:
        id: sub_341c7b5b432a3158
        callback_url: https://your_callback_url.com
        events:
        - application.updated.data.requested
        - application.approved
        - application.cancelled
        - application.declined
        - application.merchant.boarded
        status: active
        created_at: '2025-01-01T00:00:00Z'
        updated_at: '2025-01-01T00:00:00Z'
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            '*': Full access
            packages:read: Read packages information
            applications:read: Read access to applications
            applications:write: Write access to applications
            subscriptions:read: Read access to subscriptions
            subscriptions:write: Write access to subscriptions (subscribe/updated/delete)
x-provenance:
  method: searched
  source: https://docs.nmi.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.nmi.com/reference/createapplication.md
  - https://docs.nmi.com/reference/createsubscription.md
  - https://docs.nmi.com/reference/deletesubscription.md
  - https://docs.nmi.com/reference/getaccesstoken.md
  - https://docs.nmi.com/reference/getapplication.md
  - https://docs.nmi.com/reference/getapplicationdownloadagreement.md
  - https://docs.nmi.com/reference/getapplicationlegalconsent.md
  - https://docs.nmi.com/reference/getapplications.md
  - https://docs.nmi.com/reference/getpackagebyid.md
  - https://docs.nmi.com/reference/getpackages.md
  - https://docs.nmi.com/reference/getsubscription.md
  - https://docs.nmi.com/reference/getsubscriptions.md
  - https://docs.nmi.com/reference/submitapplication.md
  - https://docs.nmi.com/reference/updateapplication.md
  - https://docs.nmi.com/reference/updateapplicationinfo.md
  - https://docs.nmi.com/reference/updatesubscription.md
  - https://docs.nmi.com/reference/uploaddocument.md
  merge:
    pages: 17
    deduped: 353
    conflicts_kept_first: 0