Events

Events let you get notified about things that happen in the external application.

Each event has:

Name
Parameters (optional)
Payload schema

Events are located in the events folder of the connector. Each event has its own folder named events/<event-key> (for example, events/user-created).

Event Specification

The event specification is located in the spec.yml file in the event folder. It has the following format:

name: Task Created
implementationType: webhook
parametersSchema:
  type: object
  properties:
    projectId:
      type: string
      description: ID of the project to monitor for new tasks
  required:
    - projectId
schema:
  type: object
  properties:
    id:
      type: string
    title:
      type: string
    description:
      type: string
    status:
      type: string
methods:
  subscribe:
    implementationType: javascript
  unsubscribe:
    implementationType: javascript

Let's break it down:

Property	Description
`name`	Human-readable name of the event that will be shown in the UI
`implementationType`	Type of event implementation. Can be `webhook` or `global-webhook`
`parametersSchema`	JSON Schema describing parameters that need to be provided when subscribing to the event. In the example above, we require a `projectId` to know which project to monitor
`schema`	JSON Schema describing the event payload structure that will be received when the event occurs
`methods`	Object describing implementation methods for the event. The list of methods depends on the `type` of the event.

Implementation Types

Webhook

This event implementation type uses webhook subscriptions to get events.

When an event subscription is created, it registers a webhook and handles incoming payloads. When an event subscription is deleted, it unsubscribes from the webhook.

It optionally supports a refresh mechanism to keep the subscription active if the external app requires it.

Full article: [doc:connector-builder/events/webhook]

Global Webhook

This event implementation type uses Global Webhooks to get events.

Full article: [doc:connector-builder/events/global-webhook]