openapi: 3.0.3
info:
  title: Pinwheel Accounts Webhooks API
  description: Pinwheel is the API for direct deposit switching, bill switching, and income & employment verification.
  version: v2025-07-08
  contact:
    name: Support
    email: support@getpinwheel.com
    url: https://getpinwheel.com
servers:
- url: https://api.getpinwheel.com/v1
  description: production
- url: https://sandbox.getpinwheel.com/v1
  description: sandbox
- url: https://development.getpinwheel.com/v1
  description: development
security:
- apiSecret: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      description: List all webhooks. This is a paginated endpoint; see how Pinwheel implements pagination <a href='https://docs.pinwheelapi.com/docs/pagination-1' target='_blank'>here</a>.
      operationId: get_v1_webhooks_get
      parameters:
      - description: Cursor for the page you want to retrieve.
        required: false
        schema:
          type: string
          description: Cursor for the page you want to retrieve.
        name: cursor
        in: query
      - description: The maximum number of results to return.
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          description: The maximum number of results to return.
          default: 25
        name: limit
        in: query
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  data:
                    items:
                      $ref: '#/components/schemas/WebhookObjResponse'
                    type: array
                    title: Data
                type: object
                required:
                - meta
                - data
                x-tags:
                - Schemas
              examples:
                example:
                  value:
                    data:
                    - url: https://example.com/webhook_endpoint
                      id: ae0047bf-cd48-4f41-9fa2-2e578ca82969
                      created_at: '2020-11-06T15:59:13.530178+00:00'
                      last_updated: '2020-11-06T16:00:00.530178+00:00'
                      enabled_events:
                      - income.added
                      - employment.added
                      status: active
                      version: '2023-04-18'
                    meta:
                      count: 1
                      next_cursor: eyJpZCI6ICIwMzIwYzczYS02NWYyLTRkMDktOTMxNC1jZTAyMzFiZjYwZDYifQ==
    post:
      tags:
      - Webhooks
      summary: Create Webhook
      description: Create a webhook to use for callbacks from Pinwheel jobs.
      operationId: post_v1_webhooks_post
      parameters:
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate_v2023_04_18'
            examples:
              example:
                value:
                  url: https://example.com/webhook_endpoint
                  enabled_events:
                  - income.added
                  - employment.added
                  status: active
                  version: '2023-04-18'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookObjResponse'
                type: object
                required:
                - data
                x-tags:
                - Schemas
              examples:
                example:
                  value:
                    data:
                      url: https://example.com/webhook_endpoint
                      id: ae0047bf-cd48-4f41-9fa2-2e578ca82969
                      created_at: '2020-11-06T15:59:13.530178+00:00'
                      last_updated: '2020-11-06T16:00:00.530178+00:00'
                      enabled_events:
                      - income.added
                      - employment.added
                      status: active
                      version: '2023-04-18'
  /webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook
      description: Get webhook by id.
      operationId: get_webhook_by_id_v1_webhooks__webhook_id__get
      parameters:
      - description: UUID of the webhook.
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the webhook.
        name: webhook_id
        in: path
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookObjResponse'
                type: object
                required:
                - data
                x-tags:
                - Schemas
              examples:
                example:
                  value:
                    data:
                      url: https://example.com/webhook_endpoint
                      id: ae0047bf-cd48-4f41-9fa2-2e578ca82969
                      created_at: '2020-11-06T15:59:13.530178+00:00'
                      last_updated: '2020-11-06T16:00:00.530178+00:00'
                      enabled_events:
                      - income.added
                      - employment.added
                      status: active
                      version: '2023-04-18'
    put:
      tags:
      - Webhooks
      summary: Update Webhook
      description: Update webhook.
      operationId: put_v1_webhooks__webhook_id__put
      parameters:
      - description: UUID of the webhook.
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the webhook.
        name: webhook_id
        in: path
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
            examples:
              example:
                value:
                  url: https://example.com/new_webhook_endpoint
                  enabled_events:
                  - income.added
                  - employment.added
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookObjResponse'
                type: object
                required:
                - data
                x-tags:
                - Schemas
              examples:
                example:
                  value:
                    data:
                      url: https://example.com/webhook_endpoint
                      id: ae0047bf-cd48-4f41-9fa2-2e578ca82969
                      created_at: '2020-11-06T15:59:13.530178+00:00'
                      last_updated: '2020-11-06T16:00:00.530178+00:00'
                      enabled_events:
                      - income.added
                      - employment.added
                      status: active
                      version: '2023-04-18'
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      description: Delete a webhook.
      operationId: delete_v1_webhooks__webhook_id__delete
      parameters:
      - description: UUID of the webhook.
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the webhook.
        name: webhook_id
        in: path
      - name: Pinwheel-Version
        in: header
        required: true
        description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
        schema:
          enum:
          - '2025-07-08'
          - '2023-11-22'
          - '2023-07-18'
          - '2023-04-18'
          - '2022-09-09'
          - '2022-06-22'
          - '2022-03-02'
          default: '2025-07-08'
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
              examples:
                example:
                  value: {}
components:
  schemas:
    WebhookUpdate:
      properties:
        url:
          type: string
          title: url
          description: The URL of the webhook endpoints. Must be 'https://'.
        status:
          allOf:
          - type: string
            enum:
            - active
            - paused
          description: The status of the webhook.
        enabled_events:
          items:
            type: string
            enum:
            - paystubs.thirty_days_synced
            - paystubs.ninety_days_synced
            - direct_deposit_switch.added
            - verification_reports.refreshed
            - paystubs.documents.added
            - paystubs.added
            - company_connect.employments.added
            - shifts.added
            - bill.added
            - shifts.thirty_days_synced
            - account.monitoring_status.updated
            - paystubs.seven_days_synced
            - earnings_stream.payouts.refreshed
            - bill.updated
            - company_connect.status.updated
            - income.added
            - shifts.seven_days_synced
            - paystubs.fully_synced
            - identity.added
            - employment.added
            - shifts.fully_synced
            - company_connect.incomes.added
            - account.additional_connections_recommended
            - bill_switch.added
            - account.added
            - company_connect.census.added
            - paycheck_viewer.added
            - direct_deposit_allocations.added
            - bill_switch.cancelled
            - bill.reminder
            - tax_forms.added
            - documents.added
            - bill.removed
            - shifts.ninety_days_synced
          type: array
          minItems: 1
          description: The list of events enabled for this webhook.
        customer_id:
          type: string
          title: customer_id
          description: 'Banking platforms webhooks only: the customer ID associated with the platform''s customer.'
      type: object
      title: WebhookPatchBody
      x-tags:
      - Schemas
    WebhookCreate_v2023_04_18:
      properties:
        url:
          type: string
          title: url
          description: The URL of the webhook endpoints. Must be 'https://'.
        status:
          allOf:
          - type: string
            enum:
            - active
            - paused
          description: The status of the webhook.
        enabled_events:
          items:
            type: string
            enum:
            - paystubs.thirty_days_synced
            - paystubs.ninety_days_synced
            - direct_deposit_switch.added
            - verification_reports.refreshed
            - paystubs.documents.added
            - paystubs.added
            - company_connect.employments.added
            - shifts.added
            - bill.added
            - shifts.thirty_days_synced
            - account.monitoring_status.updated
            - paystubs.seven_days_synced
            - earnings_stream.payouts.refreshed
            - bill.updated
            - company_connect.status.updated
            - income.added
            - shifts.seven_days_synced
            - paystubs.fully_synced
            - identity.added
            - employment.added
            - shifts.fully_synced
            - company_connect.incomes.added
            - account.additional_connections_recommended
            - bill_switch.added
            - account.added
            - company_connect.census.added
            - paycheck_viewer.added
            - direct_deposit_allocations.added
            - bill_switch.cancelled
            - bill.reminder
            - tax_forms.added
            - documents.added
            - bill.removed
            - shifts.ninety_days_synced
          type: array
          minItems: 1
          description: The list of events enabled for this webhook.
        version:
          allOf:
          - type: string
            enum:
            - '2022-09-09'
            - '2025-07-08'
            - '2023-04-18'
            - '2023-11-22'
            - '2023-07-18'
          description: The webhook's version, which determines the format of the webhook event payloads.
        customer_id:
          type: string
          title: customer_id
          description: 'Banking platforms webhooks only: the customer ID associated with the platform''s customer.'
      type: object
      required:
      - url
      - status
      - enabled_events
      - version
      title: WebhookPostBody
      x-tags:
      - Schemas
    PaginationMeta:
      properties:
        count:
          type: integer
          title: count
          description: Number of objects returned.
        next_cursor:
          type: string
          title: next_cursor
          description: Pointer to the next page of results.
      type: object
      title: PaginationMeta
      x-tags:
      - Schemas
    WebhookObjResponse:
      properties:
        url:
          type: string
          title: url
          description: The URL of the webhook endpoints.
        status:
          allOf:
          - type: string
            enum:
            - active
            - paused
          description: The status of the webhook.
        enabled_events:
          items:
            type: string
            enum:
            - paystubs.thirty_days_synced
            - paystubs.ninety_days_synced
            - direct_deposit_switch.added
            - verification_reports.refreshed
            - paystubs.documents.added
            - paystubs.added
            - company_connect.employments.added
            - shifts.added
            - bill.added
            - shifts.thirty_days_synced
            - account.monitoring_status.updated
            - paystubs.seven_days_synced
            - earnings_stream.payouts.refreshed
            - bill.updated
            - company_connect.status.updated
            - income.added
            - shifts.seven_days_synced
            - paystubs.fully_synced
            - identity.added
            - employment.added
            - shifts.fully_synced
            - company_connect.incomes.added
            - account.additional_connections_recommended
            - bill_switch.added
            - account.added
            - company_connect.census.added
            - paycheck_viewer.added
            - direct_deposit_allocations.added
            - bill_switch.cancelled
            - bill.reminder
            - tax_forms.added
            - documents.added
            - bill.removed
            - shifts.ninety_days_synced
          type: array
          minItems: 1
          description: The list of events enabled for this webhook.
        version:
          allOf:
          - type: string
            enum:
            - '2022-09-09'
            - '2025-07-08'
            - '2023-04-18'
            - '2023-11-22'
            - '2023-07-18'
          description: The webhook's version, which determines the format of the webhook event payloads.
        customer_id:
          type: string
          title: customer_id
          description: 'Banking platforms webhooks only: the customer ID associated with the platform''s customer.'
        id:
          type: string
          format: uuid
          title: id
          description: Unique identifier for the object.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: ISO 8601 timestamp of created time.
        last_updated:
          type: string
          format: date-time
          title: last_updated
          description: ISO 8601 timestamp of the last update to this object.
      type: object
      required:
      - url
      - status
      - enabled_events
      - version
      - id
      - created_at
      - last_updated
      title: Webhook
      x-tags:
      - Schemas
  securitySchemes:
    apiSecret:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: API Secret
    bearerAuth:
      description: Bearer token
      type: http
      scheme: bearer