openapi: '3.0.1'
info:
  title: Treezor Webhook API
  version: July 31, 2026
  description: |
    The Treezor API provides a specific set of endpoints to subscribe to webhook notifications, manage the events you subscribe to, and resend webhooks if the need arises.

    For more information, please refer to the [Webhooks](/guide/webhooks/introduction.html) section of the documentation.
  contact: 
    name: Treezor
    url: https://treezor.com
  license:
    name: Proprietary
    url: https://treezor.com

servers:
  - url: https://webhook.sandbox.treezor.co
    description: Sandbox environment
  - url: https://webhook.api.treezor.co
    description: Production environment

paths:
  /settings/hooks:
    get:
      summary: Get Subscriptions
      operationId: getSubscriptions
      description: |
        Retrieve all the existing webhook subscriptions.
      tags:
        - Subscriptions
      responses:
        '200':
          description: Successfully retrieved subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  hooks: 
                    type: array
                    description: The list of subscriptions.
                    items:
                      $ref: '#/components/schemas/Subscription'
    post:
      summary: Create Subscription
      description: |
        Create a new webhook subscription.
      operationId: createSubscription
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '201':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  hooks: 
                    type: array
                    description: The list of subscriptions.
                    items:
                      $ref: '#/components/schemas/Subscription'

  /settings/hooks/{hookId}:
    delete:
      summary: Delete Subscription
      description: |
        Delete a hook subscription.
      operationId: deleteSubscription
      tags:
        - Subscriptions
      parameters:
        - name: hookId
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier of a the hook subscription.
            example: "46a508cb-1c72-48be-a42d-xxxxxa704cec"
      responses:
        '204':
          description: Hook deleted successfully

  /settings/hooks/{hookId}/events:
    get:
      summary: Get Events
      description: |
        Retrieve the list of events for a given subscription.
      operationId: getHookEvents
      tags:
        - Events
      parameters:
        - name: hookId
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier of a the hook subscription.
            example: "46a508cb-1c72-48be-a42d-xxxxxa704cec"
      responses:
        '200':
          description: Successfully retrieved subscription events
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    description: |
                      The list of events for the subscription.

                      See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
                    items:
                      $ref: '#/components/schemas/Event'
    post:
      summary: Create Events
      description: |
        Add events to a given subscription.
      operationId: createHookEvents
      tags:
        - Events
      parameters:
        - name: hookId
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier of a the hook subscription.
            example: "46a508cb-1c72-48be-a42d-xxxxxa704cec"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  description: |
                    The list of events to subscribe to.

                    See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
                  items:
                    type: string
                    example: "user.create"
              required:
                - events
      responses:
        '201':
          description: Events created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    description: |
                      The list of events for the subscription.

                      See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
                    items:
                      $ref: '#/components/schemas/Event'

  /settings/hooks/{hookId}/events/{eventName}:
    delete:
      summary: Delete Event
      description: |
        Remove an event for a a given subscription.
      operationId: deleteHookEvents
      tags:
        - Events
      parameters:
        - name: hookId
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier of a the hook subscription.
            example: "46a508cb-1c72-48be-a42d-xxxxxa704cec"
        - name: eventName
          in: path
          required: true
          schema:
            type: string
            description: The event to remove from the subscription.
            example: "user.create"
      responses:
        '204':
          description: Events deleted successfully

  /retry/query:
    post:
      summary: Query Webhook Retry
      description: |
        Generate webhook history CSV file for a given time frame.
      operationId: webhookQueryRetry
      tags:
        - Webhook Retry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookQueryInput'
      responses:
        '200':
          description: Query processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  queryId: 
                    type: string
                    description: The unique identifier of the query.
                    example: "2bd5740a-528d-451d-a726-7f57c6d82008"
                  link: 
                    type: string
                    description: The link to the webhook history CSV file.
                    example: "https://your.csv.link"
                  expireIn: 
                    type: integer
                    default: 300
                    description: The time after which the link expires in seconds.

  /retry/exec:
    post:
      summary: Execute Webhook Retry
      description: | 
        Request execution of the file to resend the events contained generated .CSV file (up to 20,000 events).
      operationId: webhookExecRetry
      tags:
        - Webhook Retry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookExecInput'
      responses:
        '200':
          description: Execution initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionId: 
                    type: string
                    description: The unique identifier of the execution request.
                    example: "12345678-1234-1234-1234-123456789abc"
                  status: 
                    type: string
                    description: The status of the execution.
                    enum: ["IN_PROGRESS", "DONE"] 
                    example: "IN_PROGRESS"

  /retry/exec/{queryId}:
    get:
      summary: Check Execution Status
      description: |
        Retrieve the status of webhook retry execution.
      operationId: checkWebhookRetryStatus
      tags:
        - Webhook Retry
      parameters:
        - name: queryId
          in: path
          required: true
          schema:
            type: string
            description: The unique identifier of the query.
            example: "2bd5740a-528d-451d-a726-7f57c6d82008"
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionId: 
                    type: string
                    description: The unique identifier of the execution request.
                    example: "12345678-1234-1234-1234-123456789abc"
                  status: 
                    type: string
                    description: The status of the execution.
                    enum: ["IN_PROGRESS", "DONE"] 
                    example: "DONE"

components:
  schemas:
    Subscription:
      type: object
      properties:
        url:
          type: string
          description: The URL of the hook subscription.
        status:
          type: string
          description: The status of the subscription.
          enum: ["ENABLED", "PENDING"]
        uuid:
          type: string
          description: The identifier of the hook subscription.
          example: "007de3c1-639d-5838-8785-2d42ffe4cbed"

    SubscriptionInput:
      type: object
      properties:
        url:
          type: string
          description: The URL of the hook subscription.
        events:
          type: array
          description: | 
            The list of events to subscribe to.

            See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
          items:
            type: string
            description: See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
            example: "user.create"
      required:
        - url

    Event:
      type: string
      description: See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
      example: "user.create"
      

    WebhookQueryInput:
      type: object
      properties:
        startAt:
          type: string
          format: date-time
          description: |
            The date and time from which to retrieve the webhooks. Format: RFC3339.
          example: "2025-06-10T12:10:00+02:00"
        endAt:
          type: string
          format: date-time
          description: |
            The date and time up to which to retrieve the webhooks. Format: RFC3339.
          example: "2025-07-08T00:00:00+02:00"
        webhook:
          type: string
          description: |
            Filter for a specific event, if need be. 
            See the [events description](/guide/webhooks/events-descriptions.html) article for the full list of events.
          example: "merchantIdGroup.create"

      required:
        - startAt
        - endAt

    WebhookExecInput:
      type: object
      properties:
        queryId:
          type: string
          description: The unique identifier of the query.
          example: "2bd5740a-528d-451d-a726-7f57c6d82008"
        delay:
          type: integer
          description: |
            The time between each webhook retry attempts in seconds, in order to not overload your servers. 
            Can't exceed 1 hour.
          minimum: 0
          maximum: 3600
          example: 60
      required:
        - queryId


  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

security:
  - BearerAuth: []


tags:
  - name: Subscriptions
    description: |
      Subscribe to webhook notifications and manage subscriptions.

      _Related articles: [Subscription management](/guide/webhooks/subscription-management.html)_
  - name: Events
    description: |
      Manage which events are sent for each subscriptions. 
      If you do not define the list of events, then Treezor sends you webhooks for all the events.

      _Related articles: [Subscription management](/guide/webhooks/subscription-management.html) | [Events description](/guide/webhooks/events-descriptions.html)_
  - name: Webhook Retry
    description: |
      Retry webhook events. Resending webhooks is a 3-step process: 
        1. **Generate webhook history CSV file** for a given time frame.
        2. **Request execution** to resend the generated file events.
        3. **Retrieve the execution status** of the webhook retry.

      _Related article: [Webhook retry](/guide/webhooks/retry.html)_