FinGoal Webhook Configurations API

openapi: 3.2.0
info:
  title: Insights Webhook Configurations API
  description: '# Overview

    Download our postman collection here.'
  version: 3.1.3
servers:
- url: https://findmoney-dev.fingoal.com/v3
  description: Insights API Development
- url: https://findmoney.fingoal.com/v3
  description: Insights API Production
security:
- Authentication: []
tags:
- name: Webhook Configurations
  description: Manage webhook callback URLs for your client. Supports default and tenant-specific configurations per webhook type.
paths:
  /webhook-configurations:
    get:
      tags:
      - Webhook Configurations
      summary: List Webhook Configurations
      description: 'Retrieve all webhook configurations for your client. Configurations are organized into:

        - **default**: Configurations without a tenant_id that apply to your client''s default callback URL

        - **tenants**: Tenant-specific configurations organized by tenant_id'
      operationId: listWebhookConfigurations
      security:
      - Authentication:
        - enrichment
      responses:
        '200':
          description: Successfully retrieved webhook configurations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_configurations:
                    type: object
                    description: All webhook configurations for your client, organized by scope.
                    properties:
                      client:
                        type: array
                        description: Default webhook configurations (no tenant_id). These apply when no tenant-specific configuration exists.
                        items:
                          $ref: '#/components/schemas/WebhookConfigurationsPut200Response'
                      by_tenant:
                        type: object
                        description: Tenant-specific webhook configurations. Keys are tenant public IDs, values are arrays of configurations for that tenant.
                        additionalProperties:
                          type: array
                          items:
                            $ref: '#/components/schemas/WebhookConfigurationsPut200Response'
                        example:
                          TEN-123456:
                          - id: 2
                            client_id: your-client-id
                            tenant_id: TEN-123456
                            webhook_type: ENRICHMENT_DATA
                            callback_url: https://tenant-specific.com/webhooks/enrichment
                            created_at: '2024-01-15T11:00:00.000Z'
                            updated_at: '2024-01-15T11:00:00.000Z'
        '400':
          description: client_id header is required.
        '401':
          description: Unauthorized.
        '403':
          description: Missing required `enrichment` scope.
    put:
      tags:
      - Webhook Configurations
      summary: Create or Update Webhook Configuration
      description: 'Create a new webhook configuration or update an existing one. Your `client_id` and `tenant_id` are automatically inferred from the bearer token on this request. To set up a webhook for a specific tenant, please ensure that the bearer token on this request as a `tenant_id` claim. If your bearer token lacks a `tenant_id`, the webhook will be created for your single-tenant environment.


        - If a configuration already exists for the same client/tenant/webhook_type combination, it will be updated.

        - If `tenant_id` is provided, your client must have a relationship with that tenant.

        - Omit `tenant_id` to set the default callback URL for your client.'
      operationId: upsertWebhookConfiguration
      security:
      - Authentication:
        - enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_type
              - callback_url
              properties:
                webhook_type:
                  $ref: '#/components/schemas/WebhookConfigurationsPutRequest'
                callback_url:
                  type: string
                  format: uri
                  description: Valid HTTPS URL for webhook delivery.
                  example: https://your-server.com/webhooks/enrichment
      responses:
        '200':
          description: Webhook configuration created or updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_configuration:
                    $ref: '#/components/schemas/WebhookConfigurationsPut200Response'
        '400':
          description: 'Bad request. Possible errors:

            - `client_id header is required`

            - `webhook_type is required`

            - `Invalid webhook_type`

            - `callback_url is required`

            - `callback_url must be a valid URL`

            '
        '401':
          description: Unauthorized.
        '403':
          description: 'Forbidden. Possible errors:

            - Missing `enrichment` scope

            - Client does not have a relationship with the specified tenant

            '
    delete:
      tags:
      - Webhook Configurations
      summary: Delete Webhook Configuration
      description: 'Remove a webhook configuration.


        - Specify `tenant_id` to delete a tenant-specific configuration.

        - Omit `tenant_id` to delete the default configuration.'
      operationId: deleteWebhookConfiguration
      security:
      - Authentication:
        - enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_type
              properties:
                webhook_type:
                  $ref: '#/components/schemas/WebhookConfigurationsPutRequest'
      responses:
        '200':
          description: Webhook configuration deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    description: Whether the configuration was successfully deleted.
                    example: true
                  id:
                    type: integer
                    description: The ID of the deleted configuration.
                    example: 1
        '400':
          description: 'Bad request. Possible errors:

            - `client_id header is required`

            - `webhook_type is required`

            - `Invalid webhook_type`

            '
        '401':
          description: Unauthorized.
        '403':
          description: Missing required `enrichment` scope.
        '404':
          description: Webhook configuration not found.
  /webhook-configurations/test:
    post:
      tags:
      - Webhook Configurations
      summary: Test Webhook
      description: 'Test your webhook endpoint by triggering a sample payload. Useful for verifying your webhook receiver is working correctly.


        The test payload varies by webhook type:

        - **ENRICHMENT_DATA**: Sample enriched transactions payload

        - **ENRICHMENT_NOTIFICATION**: Sample batch notification with batch_request_id

        - **USER_TAGS_DATA**: Sample user tags payload with created/deleted/modified arrays

        - **USER_TAGS_NOTIFICATION**: Sample notification with guid

        - **INSIGHTS**: Sample finsights array


        All test webhooks include the `X-Webhook-Verification` header for signature verification testing.'
      operationId: testWebhook
      security:
      - Authentication:
        - enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_type
              - callback_url
              properties:
                webhook_type:
                  $ref: '#/components/schemas/WebhookConfigurationsPutRequest'
                callback_url:
                  type: string
                  format: uri
                  description: URL to send the test payload to.
                  example: https://your-server.com/webhooks/enrichment
      responses:
        '200':
          description: Test webhook result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the test webhook was successfully delivered.
                    example: true
                  status:
                    type: integer
                    description: The HTTP status code returned by the callback URL.
                    example: 200
                  message:
                    type: string
                    description: A message describing the result of the test.
                    example: Test webhook sent successfully
        '400':
          description: 'Bad request. Possible errors:

            - `client_id header is required`

            - `webhook_type is required`

            - `Invalid webhook_type`

            - `callback_url is required`

            - `callback_url must be a valid URL`

            '
        '401':
          description: Unauthorized.
        '403':
          description: Missing required `enrichment` scope.
      x-webhook-payloads:
        ENRICHMENT_DATA:
          description: Data-rich Transaction Enrichment webhook payload.
          schema:
            $ref: '#/components/schemas/WebhookConfigurationsTestPostENRICHMENT_DATA'
        ENRICHMENT_NOTIFICATION:
          description: Non-data-rich Enrichment notification payload.
          schema:
            type: object
            properties:
              batch_request_id:
                type: string
                format: uuid
                description: UUID to fetch enriched data from the `/cleanup/{batch_request_id}` endpoint.
              client_id:
                type: string
                description: Your client identifier.
              tenant_id:
                type: string
                description: Tenant identifier (if tenant-specific).
        USER_TAGS_DATA:
          description: Data-rich User Tags webhook payload.
          schema:
            $ref: '#/components/schemas/WebhookConfigurationsTestPostUSER_TAGS_DATA'
        USER_TAGS_NOTIFICATION:
          description: Non-data-rich User Tags notification payload.
          schema:
            type: object
            properties:
              guid:
                type: string
                format: uuid
                description: UUID to fetch tag data from the `/users/tags/{guid}` endpoint.
              tenant_id:
                type: string
                description: Tenant identifier (if tenant-specific).
        INSIGHTS:
          description: Finsights webhook payload.
          schema:
            type: object
            properties:
              finsights:
                type: array
                items:
                  type: object
                  properties:
                    finsight_id:
                      type: string
                      format: uuid
                      description: Unique identifier for this finsight.
                    uniqueId:
                      type: string
                      description: Unique identifier linking to the source.
                    transaction_id:
                      type: string
                      description: Related transaction identifier.
                    user_id:
                      type: string
                      description: User identifier.
                    insight_text:
                      type: string
                      description: Human-readable insight/advice text.
                    insight_ctaurl:
                      type: string
                      nullable: true
                      description: Call-to-action URL (if applicable).
                    finsight_image:
                      type: string
                      nullable: true
                      description: Image URL (if applicable).
                    recommendation:
                      type: string
                      nullable: true
                      description: Actionable recommendation.
                    amountFound:
                      type: number
                      description: Dollar amount related to the insight.
                    category:
                      type: string
                      description: Transaction category.
                    amountnum:
                      type: number
                      description: Transaction amount.
                    estimatedSavingsType:
                      type: string
                      description: Savings estimation period (e.g., "monthly").
components:
  schemas:
    WebhookConfigurationsPut200Response:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for this webhook configuration.
          example: 1
        client_id:
          type: string
          description: Your client identifier.
          example: your-client-id
        tenant_id:
          type:
          - string
          - 'null'
          description: The tenant public ID for tenant-specific configurations. Null for default configurations.
          example: TEN-123456
        webhook_type:
          $ref: '#/components/schemas/WebhookConfigurationsPutRequest'
        callback_url:
          type: string
          format: uri
          description: The HTTPS URL where webhooks will be delivered.
          example: https://your-server.com/webhooks/enrichment
        created_at:
          type: string
          format: date-time
          description: The timestamp when this configuration was created.
          example: '2024-01-15T10:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: The timestamp when this configuration was last updated.
          example: '2024-01-15T10:00:00.000Z'
    WebhookConfigurationsTestPostENRICHMENT_DATA:
      type: object
      properties:
        enrichedTransactions:
          type: array
          items:
            type: object
            properties:
              accountid:
                description: The ID of the account associated with the transaction
                type: string
              accountType:
                description: The type of account associated with the transaction (e.g., 'checking', 'savings')
                type: string
              amountnum:
                description: The transaction's USD amount
                type: number
              category:
                description: The most applicable categorization for the transaction
                type: string
              categoryId:
                description: The numeric ID of the transaction's category
                type: number
              categoryLabel:
                deprecated: true
                description: A cascading hierarchy of the transaction's categories, from high-level to detail-level categorization. This field is deprecated and not recommended for use, as it may not reflect more correct information available in other 'category' fields.
                type: array
                items:
                  type: string
              address:
                description: The address associated with the transaction
                type:
                - string
                - 'null'
                example: 123 Main St
              city:
                description: The city associated with the transaction
                type:
                - string
                - 'null'
                example: Urbana
              client_id:
                type: string
                description: Your FinGoal client ID
              container:
                description: A high-level categorization of the account type. Eg, 'bank'
                type:
                - string
                - 'null'
                example: Transaction
              date:
                description: The date on which the transaction took place
                type: string
                format: date-time
              detailCategoryId:
                description: The numeric ID of the transaction's detail category
                type: number
              guid:
                description: The transaction's globally unique FinSight API issued ID
                type: string
              highLevelCategoryId:
                description: The numeric ID of the transaction's high level category
                type: number
              isPhysical:
                description: Whether the transaction was made at a physical location, or online
                type:
                - boolean
                - 'null'
                example: true
              isRecurring:
                deprecated: true
                description: This field is deprecated. Denotes whether the transaction is set to recur on a fixed interval
                type:
                - boolean
                - 'null'
                example: false
              merchantAddress1:
                description: The street address of the merchant associated with the transaction
                type:
                - string
                - 'null'
                example: 123 Main St
              merchantCity:
                description: The name of the city where the merchant is located
                type:
                - string
                - 'null'
                example: Urbana
              merchantCountry:
                description: The name of the country where the merchant is located
                type:
                - string
                - 'null'
                example: US
              merchantLatitude:
                description: The latitude of the merchant
                type:
                - string
                - 'null'
                example: '38.9517'
              merchantLogoURL:
                description: The URL resource for the merchant's logo
                type: string
              merchantLongitude:
                description: The longitude of the merchant
                type:
                - string
                - 'null'
                example: '-92.3341'
              merchantName:
                description: The name of the merchant associated with the transaction
                type:
                - string
                - 'null'
                example: Dollar General
              merchantPhoneNumber:
                description: The phone number of the merchant associated with the transaction
                type:
                - string
                - 'null'
                example: 555-555-5555
              merchantState:
                description: The name of the state where the merchant is located
                type:
                - string
                - 'null'
                example: MO
              merchantType:
                description: The merchant's type
                type:
                - string
                - 'null'
                example: retail
              merchantZip:
                description: The ZIP code where the merchant is located
                type:
                - string
                - 'null'
                example: '65401'
              original_description:
                description: The transaction description as received. This will not change
                type: string
              receiptDate:
                description: The date on which FinSight API first received the transaction
                type:
                - string
                - 'null'
                format: date-time
                example: '2024-05-01T12:00:00Z'
              requestId:
                description: A unique ID for the request the transaction came in with, for debugging purposes
                type:
                - string
                - 'null'
                example: 04f00a35-a8fa-40fd-a2ee-4af7be22ed0a
              simple_description:
                description: An easy-to-understand, plain-language transaction description
                type: string
                deprecated: true
              simpleDescription:
                description: An easy-to-understand, plain-language transaction description
                type: string
              settlement:
                description: The settlement type of the transaction (e.g., 'debit' or 'credit')
                type:
                - string
                - 'null'
                example: debit
              sourceId:
                description: The source of the transaction
                type:
                - string
                - 'null'
                example: '1234'
              state:
                description: The state associated with the transaction
                type:
                - string
                - 'null'
                example: MO
              subtype:
                description: A more detailed classification of the transaction
                type:
                - string
                - 'null'
                example: purchase
              subType:
                description: A more detailed classification that provides further information on the type of transaction.
                type:
                - string
                - 'null'
                example: purchase
              tenant_id:
                description: The ID of the tenant associated with this transaction, if one was included.
                type:
                - string
                - 'null'
                example: TNT-4b7d4b7d-4b7d-4b7d-4b7d-4b7d4b7d4b7d
              transactionid:
                description: The ID of the transaction as it was originally submitted
                type: string
              transactionTags:
                description: The FinSight API issued tags for the transaction
                type: array
                items:
                  type: string
              transactionTagsId:
                description: The numeric IDs corresponding to the transaction tags
                type: array
                items:
                  type: integer
              type:
                description: An attribute describing the nature of the intent behind the transaction.
                type: string
              uid:
                description: The ID of the user associated with the transaction, as originally submitted
                type: string
              website:
                description: The merchant's website URL
                type:
                - string
                - 'null'
                example: https://links.fingoal.com/dollar-general
              zip_code:
                description: The ZIP code associated with the transaction
                type:
                - string
                - 'null'
                example: '65401'
        failedTransactions:
          type: array
          items:
            type: object
            properties:
              transactionid:
                description: The ID of the transaction as received.
                type: string
              amountnum:
                description: The transaction's USD amount as received.
                type: number
              original_description:
                description: The transaction description as received.
                type: string
              uid:
                description: The ID of the user associated with the transaction, as received.
                type: string
              date:
                description: The date on which the transaction took place as received.
                type: string
                format: date-time
              settlement:
                description: The transaction's settlement type as received.
                type: string
              accountType:
                description: The type of account associated with the transaction as received.
                type: string
    WebhookConfigurationsPutRequest:
      type: string
      enum:
      - ENRICHMENT_DATA
      - ENRICHMENT_NOTIFICATION
      - USER_TAGS_DATA
      - USER_TAGS_NOTIFICATION
      - INSIGHTS
      description: 'The type of webhook to configure:

        - `ENRICHMENT_DATA`: Data-rich Transaction Enrichment webhooks (full payload)

        - `ENRICHMENT_NOTIFICATION`: Non-data-rich Enrichment webhooks (notification only, fetch data from the `/cleanup/{batch_request_id}` endpoint)

        - `USER_TAGS_DATA`: Data-rich User Tags webhooks (full payload)

        - `USER_TAGS_NOTIFICATION`: Non-data-rich User Tags webhooks (notification only)

        - `INSIGHTS`: Finsights/insights webhooks

        '
    WebhookConfigurationsTestPostUSER_TAGS_DATA:
      type: object
      properties:
        tenant_id:
          type: string
          description: The ID of the tenant for the users included in this update, if they are from a tenant environment.
        userTags:
          type: object
          properties:
            created:
              description: A list of the new user tags that were generated for this user since the last user tagging update. A full list of the user tags can be accessed [here](https://fingoal.com/tags-list).
              type: array
              items:
                type: object
                properties:
                  user_id:
                    description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
                    type: string
                    example: '409088'
                  user_tag_id:
                    description: The ID of the tag that has been applied.
                    type: integer
                    example: 61
                  tag_name:
                    description: The name of the tag that has been applied.
                    type: string
                    example: Home Improvement Loan
            deleted:
              description: A list of the user tags that were removed from this user since the last user tagging update.
              type: array
              items:
                type: object
                properties:
                  user_id:
                    description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
                    type: string
                    example: '409088'
                  user_tag_id:
                    description: The ID of the tag that has been removed.
                    type: integer
                    example: 46
                  tag_name:
                    description: The name of the tag that has been removed.
                    type: string
                    example: Movie Goer
            modified:
              description: For incremental (that is, scored) user tags. Contains all scoring changes for any incremental user tags that have received a score change since the last update.
              type: array
              items:
                type: object
                properties:
                  user_id:
                    description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
                    type: string
                    example: '409088'
                  user_tag_id:
                    description: The ID of the tag that has been updated.
                    type: integer
                    example: 46
                  tag_name:
                    description: The name of the tag that has been updated.
                    type: string
                    example: Movie Goer
                  previous_value:
                    description: The last value for this tag's score, prior to this update.
                    type: integer
                    example: 50
                  new_value:
                    description: The new value for this tag's score.
                    type: integer
                    example: 75
                  delta:
                    description: The amount by which this tag's score has changed. Can be negative or positive. Will be the difference between the new_value and previous_value fields.
                    type: integer
                    example: 25
  securitySchemes:
    Authentication:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://findmoney.fingoal.com/v3/authentication
          scopes:
            enrichment: Grants access to the transaction enrichment APIs.
x-provenance:
  method: harvested
  publisher: FinGoal
  source: https://docs.fingoal.dev/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)