Talon.One Webhooks API

openapi: 3.2.0
info:
  title: Management Webhooks API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Webhooks
  description: 'Represents webhooks, which send information from Talon.One to the URI of your choice.


    See the docs.'
paths:
  /v1/webhooks:
    get:
      operationId: getWebhooks
      summary: List webhooks
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        List all webhooks.'
      tags:
      - Webhooks
      parameters:
      - name: applicationIds
        in: query
        description: 'Checks if the given catalog or its attributes are referenced in the specified Application ID.


          **Note**: If no Application ID is provided, we check for all connected Applications.

          '
        example: '33'
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: creationType
        in: query
        description: Filter results by creation type.
        example: webhooks
        required: false
        schema:
          type: string
          enum:
          - templateWebhooks
          - webhooks
      - name: visibility
        in: query
        description: Filter results by visibility.
        example: visible
        required: false
        schema:
          type: string
          enum:
          - visible
          - hidden
      - name: outgoingIntegrationsTypeId
        in: query
        description: Filter results by outgoing integration type ID.
        example: 15
        required: false
        schema:
          type: integer
      - name: title
        in: query
        description: Filter results performing case-insensitive matching against the webhook title.
        example: title1
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookWithOutgoingIntegrationDetails'
  /v1/webhooks/{webhookId}:
    get:
      operationId: getWebhook
      summary: Get webhook
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Returns a webhook by its id.'
      tags:
      - Webhooks
      parameters:
      - name: webhookId
        description: 'The ID of the webhook. You can find the ID in the Campaign Manager''s URL when you display the details of the webhook in **Account** > **Webhooks**.

          '
        example: 11
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
components:
  schemas:
    NewWebhook:
      type: object
      required:
      - title
      - verb
      - url
      - headers
      - params
      - draft
      - enabled
      - applicationIds
      properties:
        applicationIds:
          type: array
          description: 'The IDs of the Applications in which this webhook is available.

            An empty array means the webhook is available in `All Applications`.

            '
          items:
            type: integer
        title:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
          description: Name or title for this webhook.
          example: Send message
        description:
          type: string
          description: A description of the webhook.
          example: A webhook to send a coupon to the user.
        draft:
          type: boolean
          description: Indicates if the webhook is a draft.
          example: false
        verb:
          type: string
          enum:
          - POST
          - PUT
          - GET
          - DELETE
          - PATCH
          description: API method for this webhook.
          example: POST
        url:
          type: string
          description: API URL (supports templating using parameters) for this webhook.
          example: www.my-company.com/my-endpoint-name
        headers:
          type: array
          description: List of API HTTP headers for this webhook.
          items:
            type: string
            pattern: ^([^:,]*):([^]*|[^,]*)$
          example:
          - '{"Authorization": "Basic bmF2ZWVua3VtYXIU="}'
          - '{"Content-Type": "application/json"}'
        payload:
          type: string
          description: API payload (supports templating using parameters) for this webhook.
          example: "{\n\t\"message\": \"${message}\"\n}"
        params:
          type: array
          description: Array of template argument definitions.
          items:
            $ref: '#/components/schemas/TemplateArgDef'
          example: []
        enabled:
          type: boolean
          description: Enables or disables webhook from showing in the Rule Builder.
          example: true
        authenticationId:
          type: integer
          description: The ID of the credential that this webhook is using.
          example: 1
    MutableEntity:
      type: object
      required:
      - modified
      properties:
        modified:
          type: string
          format: date-time
          description: The time this entity was last modified.
          example: '2021-09-12T10:12:42Z'
    FuncArgDef:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - string
          - boolean
          - number
          - time
          - (list string)
          - (list number)
          description: The type of value this argument expects.
          minLength: 1
        description:
          type: string
          description: A campaigner-friendly description of the argument, this will also be shown in the rule editor.
    WebhookWithOutgoingIntegrationDetails:
      allOf:
      - $ref: '#/components/schemas/Webhook'
      - type: object
        properties:
          outgoingIntegrationTemplateId:
            type: integer
            description: Identifier of the outgoing integration template.
            example: 1
          outgoingIntegrationTypeId:
            type: integer
            description: Identifier of the outgoing integration type.
            example: 1
          outgoingIntegrationTypeName:
            type: string
            description: Name of the outgoing integration.
            example: Braze
    Webhook:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/MutableEntity'
      - $ref: '#/components/schemas/NewWebhook'
    TemplateArgDef:
      allOf:
      - $ref: '#/components/schemas/FuncArgDef'
      - type: object
        required:
        - ui
        - title
        properties:
          title:
            type: string
            description: A campaigner friendly name for the argument, this will be shown in the rule editor.
            minLength: 1
          ui:
            type: object
            description: Arbitrary metadata that may be used to render an input for this argument.
          key:
            type: string
            description: The identifier for the associated value within the JSON object.
          picklistID:
            type: integer
            description: ID of the picklist linked to a template.
          restrictedByPicklist:
            type: boolean
            description: Whether or not this attribute's value is restricted by picklist (`picklist` property)
    Entity:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
  parameters:
    sort:
      name: sort
      in: query
      required: false
      description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`.


        **Note:** You may not be able to use all fields for sorting. This is due to performance limitations.

        '
      example: name
      schema:
        type: string
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
    pageSize:
      name: pageSize
      in: query
      required: false
      description: The number of items in the response.
      example: 1000
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
  securitySchemes:
    manager_auth:
      type: apiKey
      name: Authorization
      in: header
      description: 'This authentication scheme relies on a bearer token that you can use to

        access all the endpoints of the Management API.


        To create the token:


        1. Get a bearer token by calling the

        [createSession](#tag/Sessions/operation/createSession) endpoint.

        1. Use the `token` property of the response in the HTTP header of your

        next queries: `Authorization: Bearer $TOKEN`.


        A token is valid for 3 months. In accordance with best pratices, use

        your generated token for all your API requests. Do **not** regenerate a token for each

        request.


        > [!note]

        > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)

        > instead of a bearer token.

        '
    management_key:
      type: apiKey
      name: Authorization
      in: header
      description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"