Core

Triggers

Triggers allow you to set up real time integrations with hundreds of underlying services (Ex. Salesforce, Slack, Jira etc.).

The job of setting webhooks, subscripting to events from a 3rd party system can be made hassle free by using the vast library of Tray Triggers.

Here is how you can implement a basic use case of notifying Sales channel in Slack for new / updated leads in Salesforce:

Use the Salesforce trigger to listen for any new/updated lead
Grab the lead data using find_record operation of Salesforce connector
Format data to be sent to Slack
Send a Slack notification using send_message operation of Slack connector

List Subscriptions

This endpoint is non-billable.

Returns a paginated list of susbcriptions.

You can use the pageInfo parameters to traverse through pages and collect response.

If hasNextPage is true then pass the endCursor to query parameter after to obtain the next page of response.

Response Examples

{
  "elements": [
    {
      "id": "",
      "externalId": "",
      "publicUrl": "",
      "name": "",
      "trigger": {
        "name": "slack-trigger",
        "version": "7.0",
        "operation": "events_api"
      },
      "endpoints": {
        "connectorEventEndpoint": "",
        "stateChangeEventEndpoint": ""
      },
      "state": "ACTIVE"
    },
    {
      "id": "",
      "externalId": "",
      "publicUrl": "",
      "name": "",
      "trigger": {
        "name": "slack-trigger",
        "version": "7.0",
        "operation": "events_api"
      },
      "endpoints": {
        "connectorEventEndpoint": "",
        "stateChangeEventEndpoint": ""
      },
      "state": "CREATION_FAILED",
      "errorMessage": "Subscription could not be created. Reason: "
    }
  ],
  "pageInfo": {
    "startCursor": "",
    "endCursor": "",
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Create Subscription

Delivery of event payloads after a subscription is created are billable.

Every event payload that is processed (see note below) by Tray is billed as 1 task.

Note: Processed events include:

Events that were delivered to your subscription URL successfully
Events where Tray attempted delivery but your endpoint doesn't respond after retries
Events which you filter out at the connector level e.g. applying a filter condition using pick val on salesforce 'on record create'.

Since all of the above events were processed by Tray, these will be billed.

Creates a subscription using a trigger operation and returns the state of subscription.

The input is a regular json object that must fit the input schema of the operation as retrieved from Get trigger operations.

The authId field should be the id of a previously created authentication.

The output is also a regular json object containing the response from the 3rd party. The state field indicates the current status of the subscription.

This reqest has a 60 seconds timeout, if the subscription is created successfully within 60 seconds, you will receive a response with active state.

Event payload

Once a subscription is in active state, the events would start coming at the endpoint defined the request.

Here is how the event payload may look like:

{
    "id": "<uuid>",
    "subscription": {
        "id": "<uuid>",
        "externalId": "<external_id>"
    },
    "outcome": "success",
    "body": {},
    "timestamp": "2023-04-13 10:04:00Z"
}

If the outcome is success, the body in the above payload would follow the Output Schema of the trigger operation.

You can visualize the sample event payloads from any Trigger in the Operations Explorer app.

If the outcome is failure, then manual testing with the API is required as every 3rd party service would have it's own failure responses.

Request Examples

{
  "name": "test-typeform-subscription",
  "trigger": {
    "name": "typeform-trigger",
    "version": "4.1"
  },
  "operation": "webhook",
  "authenticationId": "1a7f8a5b-6848-438a-8317-f09876d521ab",
  "input": {
    "form_id": "R8B26k6g"
  },
  "endpoint": "https://9e2cf626-c0b6-4764-884a-b7bf33200b41.trayapp.io"
}

Response Examples

{
  "id": "bcbbxxxx-xxxx-xxxx-xxxx-xxxx524030e5",
  "name": "John Doe's Typeform subscription",
  "trigger": {
    "name": "typeform-trigger",
    "version": "4.1"
  },
  "operation": "events_api",
  "authenticationId": "1a7fxxxx-xxxx-xxxx-xxxx-xxxx76d521ab",
  "endpoint": "",
  "input": {
    "form_id": {
      "type": "string",
      "value": "R8B26k6g"
    },
    "public_url": {
      "type": "jsonpath",
      "value": "$.env.public_url"
    }
  },
  "state": "active",
  "signingKey": "ilYCCd7R40K1Ba9ra7k3VdKLKEUw9y9fvCiLEGGJdO/Gz73zqvR16IxUyZc3+ieGJsdfXz3Z0H8+ubb3wVtJLw=="
}

Get Subscription

This endpoint is non-billable.

Returns a single subscription object using subscription ID as the parameter.

Response Examples

{
  "id": "",
  "externalId": "",
  "publicUrl": "",
  "name": "",
  "trigger": {
    "name": "slack-trigger",
    "version": "7.0"
  },
  "operation": "events_api",
  "endpoint": "",
  "state": "active"
}

Delete Subscription

This endpoint is non-billable.

Deletes a subscription using subscription ID as the parameter.

Response Examples

{
  "message": "string",
  "code": "string"
}

List Triggers

This endpoint is non-billable.

Returns a list with all the available triggers from Tray's trigger library. A trigger can have multiple versions.

The following key data is returned:

Service name and version are required inputs for Get service environments
Trigger name and version are required inputs for Get trigger operations and Create subscription
The service id is required for building the url for the Auth-only dialog.

Response Examples

{
  "elements": [
    {
      "name": "slack-trigger",
      "description": "Slack brings all your communication together in one place. It's real-time messaging, archiving and search for modern teams.",
      "service": {
        "id": "3e21b055-xxxx-xxxx-xxxx-72af0843b283",
        "name": "slack",
        "version": 4
      },
      "version": "7.0",
      "title": "Slack trigger"
    },
    {
      "name": "shopify-trigger",
      "service": {
        "id": "e0b2cbd7-xxxx-xxxx-xxxx-31d028968e0b",
        "name": "shopify",
        "version": 4
      },
      "title": "Shopify",
      "version": "4.1",
      "description": "Shopify gives you everything you need to build a successful online business."
    }
  ]
}

List Trigger Operations

This endpoint is non-billable.

Returns a list with all the available operations for a given trigger

Each trigger operation has an input schema that can be used by a frontend to build a form or validate data.

You can then use the input schema to construct your inputs for the 'Create subscription' operation.

Response Examples

{
  "elements": [
    {
      "name": "events_api",
      "title": "On Slack event",
      "description": "",
      "inputSchema": {
        "$schema": "https://api.tray.io/core/v1/triggers/operations/input-schema#",
        "advanced": [],
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              {
                "text": "A channel was archived",
                "value": "channel_archive"
              },
              {
                "text": "A channel was created",
                "value": "channel_created"
              }
            ],
            "description": "",
            "title": "Event"
          }
        },
        "required": [
          "event"
        ]
      },
      "authScopes": [
        "chat:write:bot",
        "chat:write:user"
      ]
    }
  ]
}