Rocket Lawyer Event Consumption API

openapi: 3.2.0
info:
  title: Events Event Consumption API
  version: '1'
  description: 'This API documentation describes the server-side contract by which Rocket Lawyer Events can be subscribed to and events can be pulled using the Partner Events API.


    Steps to pull events -

    1. Use POST /subscriptions API to create a subscription

    2. Use POST /subscriptions/{subscriptionId}/eventPulls API to pull events

    3. Use POST /subscriptions/{subscriptionId}/eventAcknowledgements to acknowledge the pulled events'
servers:
- url: https://api-sandbox.rocketlawyer.com/events/v1
  description: Sandbox
- url: https://api.rocketlawyer.com/events/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Event Consumption
paths:
  /subscriptions/{subscriptionId}/eventPulls:
    parameters:
    - name: subscriptionId
      in: path
      description: ''
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    post:
      tags:
      - Event Consumption
      operationId: createEventPull
      description: 'Pull a batch of pending events for this subscription. Pulled events must be acknowledged promptly

        or else they will be redelivered in subsequent event pulls.


        Retention: Events have a retention period of 7 days.


        Authorization\: Requires a general access or scoped access token.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPullPost'
      responses:
        200:
          description: The event pull request has been performed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPull'
        403:
          description: You do not have sufficient permission to pull events from this subscription
        404:
          description: The subscription does not exist
      summary: Create event pull
      x-summary-source: derived
  /subscriptions/{subscriptionId}/eventAcknowledgements:
    parameters:
    - name: subscriptionId
      in: path
      description: ''
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    post:
      tags:
      - Event Consumption
      operationId: createEventAcknowledgement
      description: 'Acknowledge a set of events to prevent them from being re-delivered


        Authorization\: Requires a general access or scoped access token.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventAcknowledgementPost'
      responses:
        200:
          description: The events are acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventAcknowledgement'
        403:
          description: You do not have sufficient permission to acknowledge events from this subscription
        404:
          description: The subscription does not exist
      summary: Create event acknowledgement
      x-summary-source: derived
components:
  schemas:
    EventCoreProperties:
      description: A set of core properties which may be provided for any event
      type: object
      properties:
        eventTimestamp:
          type: string
          format: date-time
          example: '2021-12-11T15:00:50.338Z'
          description: The approximate time when the event occurred
        eventUniqueId:
          type: string
          format: uuid
          example: 4a42d30f-a13a-4034-90fd-7cb2679c0253
          description: 'A unique ID for this event, which is constant across retries. Please note

            that our event system uses _at least once delivery_. This means that it

            is possible for there to be duplicates deliveries of a given event. For

            this reason, partners are advised to use the eventUniqueId to deduplicate

            events within their systems if repeated processing is undesirable.

            '
        relatedRlRequestId:
          type:
          - string
          - 'null'
          format: uuid
          example: ac871cfc-1f21-4a02-b81e-11a48eef0386
          description: 'A unique ID to allow cross-correlating events that originate from the same underlying request to a

            Rocket Lawyer API. This is provided on a best-effort basis.

            '
        relatedSessionId:
          type:
          - string
          - 'null'
          format: uuid
          example: 1b305d40-7c28-4d2f-8e36-4726179d38b9
          description: 'A unique ID to allow cross-correlating events that originate from the same underlying session.

            '
      required:
      - eventTimestamp
      - eventUniqueId
    EventHandle:
      description: An opaque string that allows a specific event to be acknowledged
      type: string
      example: RVNEUAYWLF1GSFE3GQhoUQ5PXiM_NSAoRREICBQFfH1yQ1V1VTN1B1ENGXN6MnI7XkUBBRcFdF9RGx9ZXET_zPq2L1BdYndrWBUJAERSfFtYGQlqVHTo_4y_tfqXVG9WYpnKqf5lXv6uhbtZZiE9XxJLLD5-LTJFQV5AEkwmB0RJUytDCypYEU4EISE-MD4
    EventPull:
      description: A fullfilled request to pull events from a given subscription
      type: object
      properties:
        eventPullId:
          $ref: '#/components/schemas/EventPullId'
        maxEvents:
          $ref: '#/components/schemas/MaxEventCount'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
      required:
      - eventPullId
      - maxEvents
      - events
    EventPullId:
      description: 'An ID which may be used to reference a specific event pull in communication with Rocket Lawyer. If an event pull ID is not provided,

        one will be generated automatically. If an ID _is_ provided, it should have a unique value for each each event pull.

        '
      type: string
      format: uuid
      example: bd329b6c-f4d0-4606-b179-4dbbc69ecedf
    EventPullPost:
      description: A request to pull events from a subscription
      type: object
      properties:
        maxEvents:
          $ref: '#/components/schemas/MaxEventCount'
    SubscriptionId:
      description: The ID for a specific subscription.
      type: string
      format: uuid
      example: f3443a23-301d-4b6b-a178-3840d8cb9e5f
    EventAcknowledgementPost:
      description: A request to acknowledge a set of events
      type: object
      properties:
        eventHandles:
          type: array
          items:
            $ref: '#/components/schemas/EventHandle'
      required:
      - eventHandles
    Event:
      description: An event which occurred within the Rocket Lawyer platform
      type: object
      properties:
        eventHandle:
          $ref: '#/components/schemas/EventHandle'
        coreProperties:
          $ref: '#/components/schemas/EventCoreProperties'
        name:
          type: string
          example: session-established
        payload:
          $ref: '#/components/schemas/EventPayload'
      required:
      - eventHandle
      - coreProperties
      - name
    MaxEventCount:
      type: string
      format: unsigned-int32
      example: '20'
      description: The maximum number of events to include in an event pull. Note that a smaller number of events might be included in the actual pull.
    EventPayload:
      description: 'Extra event context. The contents of this payload will differ for each type of event so the "name" field

        should be consulted before trying to interpret it.

        '
      type: object
      example:
        userAgent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36
    EventAcknowledgementId:
      description: 'An ID which may be used to reference a specific event acknowledgement in communication with Rocket Lawyer. If an event acknowledgement ID is

        not provided, one will be generated automatically. If an ID _is_ provided, it should have a unique value for each each acknowledgement request.

        '
      type: string
      format: uuid
      example: ae416a84-f5cc-49f5-8706-e0e2fa57c21c
    EventAcknowledgement:
      description: A fulfilled request to acknowledge a set of events
      type: object
      properties:
        eventAcknowledementId:
          $ref: '#/components/schemas/EventAcknowledgementId'
        eventHandles:
          type: array
          items:
            $ref: '#/components/schemas/EventHandle'
      required:
      - eventAcknowledgementId
      - eventHandles
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT