Gladly Webhooks API

openapi: 3.2.0
info:
  title: Gladly Webhooks API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Webhooks
  description: A **Webhook** is a way to send notifications about Gladly events as a POST request to the endpoint of your choice.
paths:
  /api/v1/webhooks:
    post:
      tags:
      - Webhooks
      summary: Create Webhook
      description: 'Create a new webhook with the supplied data. The webhook will be in disabled state by default.


        If creating a new enabled webhook, your service is expected to respond to a Ping Event.


        You are limited to 20 webhooks for your organization.'
      operationId: createWebhook
      requestBody:
        required: true
        description: Webhook to add
        content:
          application/json:
            schema:
              title: Webhook
              allOf:
              - $ref: '#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema'
              - type: object
                required:
                - url
                - events
            example:
              name: CSAT integration
              url: https://gateway.organization.com/gladly/webhook
              events:
              - CONVERSATION/CLOSED
              credentials:
                username: integrations@organization.com
                password: fxdUfTcejVxVs9bQ8DizKccq
              headers:
                X-Gladly-Token: '123'
      callbacks:
        event:
          '{$request.body#/url}':
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema'
              responses:
                '200':
                  description: Event was accepted
      responses:
        '201':
          description: Created webhook
          headers:
            Location:
              schema:
                type: string
                example: /api/v1/webhooks/c5yeqK8VTlm9xAXgvq_5-w
              description: Location of the created webhook
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      description: Returns a list of webhooks.
      operationId: getWebhooks
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                title: Webhooks
                type: array
                items:
                  $ref: '#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema'
  /api/v1/webhooks/{webhookId}:
    parameters:
    - name: webhookId
      in: path
      description: id of the webhook
      required: true
      schema:
        type: string
        example: a9dIl-kKRrKUZLQtJ-tjtw
    patch:
      tags:
      - Webhooks
      summary: Update Webhook
      description: 'Update webhook by id.


        If enabling a webhook or updating a webhook''s URL, your service is expected to respond to a Ping Event.'
      operationId: updateWebhook
      requestBody:
        required: true
        description: JSON patch of webhook properties to insert or update
        content:
          application/json:
            schema:
              title: Webhook
              allOf:
              - title: Webhook
                properties:
                  id:
                    type: string
                    readOnly: true
                    description: id of the webhook
                    example: a9dIl-kKRrKUZLQtJ-tjtw
                  name:
                    type: string
                    maxLength: 200
                    description: friendly name of the webhook
                    example: CSAT integration
                  events:
                    type: array
                    description: list of events that trigger the webhook. More events are coming soon. Please see [Events](#operation/Events) for more information about the data included for each event type.
                    example:
                    - CONVERSATION/CLOSED
                    items:
                      type: string
                      enum:
                      - AGENT_AVAILABILITY/FOCUS_ENTERED
                      - AGENT_AVAILABILITY/FOCUS_EXITED
                      - AGENT_AVAILABILITY/UPDATED
                      - AGENT_STATUS/CHANGED_ACTIVE_REASON
                      - AGENT_STATUS/LOGGED_IN
                      - AGENT_STATUS/LOGGED_OUT
                      - AGENT_STATUS/RETURNED_FROM_AWAY
                      - AGENT_STATUS/WENT_AWAY
                      - CONTACT/ENDED
                      - CONTACT/FULFILLED
                      - CONTACT/HOLD_ENDED
                      - CONTACT/HOLD_STARTED
                      - CONTACT/JOINED
                      - CONTACT/MESSAGE_RECEIVED
                      - CONTACT/MESSAGE_SENT
                      - CONTACT/OFFER_ACCEPTED
                      - CONTACT/OFFERED
                      - CONTACT/OFFER_REJECTED
                      - CONTACT/STARTED
                      - CONTACT/TRANSFERRED
                      - CONVERSATION/CLOSED
                      - CONVERSATION/CREATED
                      - CONVERSATION/CUSTOM_ATTRIBUTE_ADDED
                      - CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED
                      - CONVERSATION/NOTE_CREATED
                      - CONVERSATION/REOPENED
                      - CONVERSATION/TOPIC_ADDED
                      - CONVERSATION/TOPIC_REMOVED
                      - CONVERSATION_ASSIGNEE/UPDATED
                      - CONVERSATION_STATUS/UPDATED
                      - CUSTOMER/MERGED
                      - CUSTOMER_PROFILE/CREATED
                      - CUSTOMER_PROFILE/DELETED
                      - CUSTOMER_PROFILE/MERGED (deprecated)
                      - CUSTOMER_PROFILE/UPDATED
                      - EXPORT_JOB/COMPLETED
                      - EXPORT_JOB/FAILED
                      - PAYMENT_REQUEST/CREATED
                      - PAYMENT_REQUEST/STATUS_CHANGED
                      - PAYMENT_REQUEST/VIEWED
                      - TASK/ASSIGNEE_UPDATED
                      - TASK/CLOSED
                      - TASK/COMMENT_ADDED
                      - TASK/CONTENT_UPDATED
                      - TASK/CREATED
                      - TASK/DUE_DATE_UPDATED
                      - TASK/FOLLOWER_ADDED
                      - TASK/FOLLOWER_REMOVED
                      - TASK/REOPENED
                  url:
                    type: string
                    description: your URL that POST requests are sent to when events occur. HTTPS is required and this value must be unique across all webhooks.
                    example: https://gateway.organization.com/gladly/webhook
                  credentials:
                    title: Basic Auth Credentials
                    writeOnly: true
                    required:
                    - username
                    - password
                    properties:
                      username:
                        type: string
                        description: basic auth username
                        example: integrations@organization.com
                      password:
                        type: string
                        description: basic auth password
                        example: ''
                      realm:
                        type: string
                        description: optional realm to authenticate with
                        example: ''
                  headers:
                    title: HTTP Headers
                    type: object
                    description: custom HTTP headers to include in every request
                    writeOnly: true
                    additionalProperties:
                      type: string
                      description: static value for the HTTP header
                    example:
                      X-API-key: <sharedSecretToken>
                      X-Gladly-token: <sharedSecretToken>
                  createdAt:
                    type: string
                    format: RFC3339
                    readOnly: true
                    description: time the webhook was created
                    example: '2019-07-03T04:30:12.07Z'
                  updatedAt:
                    type: string
                    format: RFC3339
                    readOnly: true
                    description: time the item was last updated
                    example: '2019-07-09T09:00:10.00Z'
                  hasCredentials:
                    type: boolean
                    readOnly: true
                    description: whether the webhook has been configured with basic auth credentials
                    example: true
                  headerKeys:
                    type: array
                    readOnly: true
                    description: list of header keys (without values) to include in every request to your URL.
                    example:
                    - X-Gladly-Key
                    items:
                      type: string
              - type: object
                properties:
                  enabled:
                    type: boolean
                    default: false
                    description: whether the webhook is delivering notifications
                    example: false
                  disabledAtDueToRetryLimit:
                    type: string
                    format: RFC3339
                    readOnly: true
                    description: time the webhook was disabled due to our retry limit
                    example: '2019-07-10T12:00:00.00Z'
            example:
              enabled: true
      responses:
        '204':
          description: Updated webhook
        '400':
          description: Invalid field(s) in request body
        '404':
          description: Webhook with id does not exist
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      description: Delete a webhook by ID
      operationId: deleteWebhook
      responses:
        '204':
          description: Webhook deleted
        '400':
          description: Webhook must be disabled to be deleted
        '404':
          description: Webhook with id does not exist
    get:
      tags:
      - Webhooks
      summary: Get Webhook
      description: Get a webhook by ID
      operationId: getWebhook
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema'
        '404':
          description: Webhook with id does not exist
components:
  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

        | ----------- | --------- |

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon