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:

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

List Triggers

get/core/v1/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:

SecuritybearerAuth
Request
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - returns an elements array which contains the name and version
(required for Get service environments Get trigger operations and Create subscription)

Response Schema: application/json
Array of objects (PublicConnectorEventsTrigger)
400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "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

get/core/v1/triggers/{trigger-name}/versions/{trigger-version}/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.

SecuritybearerAuth
Request
path Parameters
trigger-name
required
string

The name of the trigger

Example: slack
trigger-version
required
string

The version of the trigger

Example: 9.1
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - Returns an elements array which contains the input schema for Create subscription

Response Schema: application/json
Array of objects (PublicConnectorEventsTriggerOperation)
400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "elements": [
    • {
      • "name": "events_api",
      • "title": "On Slack event",
      • "description": "",
      • "inputSchema": {
        • "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"
        ]
      }
    ]
}

Create Subscription

post/core/v1/subscriptions

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:

  1. Events that were delivered to your subscription URL successfully
  2. Events where Tray attempted delivery but your endpoint doesn't respond after retries
  3. 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](https://developer.tray.io/developer-portal/dev-tools/ops-explorer/introduction/ops-explorer-tool/) 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.

SecuritybearerAuth
Request
header Parameters
Authorization
string

This must be a user token to call the connector on behalf of an end user. Note that authID must belong to the end user whose user token is being used.
If master token is used, you would essentially be calling the connector from your Tray account. Note that authID must belong to your account.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Request Body schema: application/json
required
object (PublicConnectorEventsTriggerReference)

Reference to link the Trigger

operation
required
string

programmatic name of the Trigger operation. Obtained using Get Trigger operations

authenticationId
string <uuid>

Unique id of the auth returned by Create Authentication

required
object
externalId
string

Unique identifier for the subscription in your database.

endpoint
required
string

The URL where you want to receive the payloads from the Subscription.

name
required
string

Name of the Subscription. Can be used to display in the UI.

Responses
200

Ok - Returns the deatils of the Subscription object.

Response Schema: application/json
authenticationId
string <uuid>

Unique id of the auth returned by Create Authentication

endpoint
required
string

The URL where you want to receive the payloads from the Subscription.

object

This is returned when subscripton creation fails on the third party service. state will be 'creation_failed'.

externalId
string

Unique identifier for the subscription in your database. Will only be returned if you passed it in the request.

id
required
string

Unique ID of the subscription in Tray's database.

required
object
name
required
string

Name of the subcription

operation
required
string

Trigger operation used to create subscription

signingKey
required
string

Unique key that can be used to verify the source of payload was Tray. Read the guide here for explanation.

state
required
string (SubscriptionState)

Current state of the subcription

Enum: "creating" "creation_failed" "deleted" "active"
required
object (PublicConnectorEventsTriggerReference)

Details about the trigger name and version

400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples
application/json
{
  • "name": "test-typeform-subscription",
  • "trigger": {
    • "name": "typeform-trigger",
    • "version": "4.1"
    },
  • "operation": "webhook",
  • "authenticationId": "1a7f8a5b-6848-438a-8317-f09876d521ab",
  • "input": {
    • "form_id": "R8B26k6g"
    },
}
Response samples
application/json
{
  • "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": "<endpoint_to_send_connector_events_to>",
  • "input": {
    • "form_id": {
      • "type": "string",
      • "value": "R8B26k6g"
      },
    • "public_url": {
      • "type": "jsonpath",
      • "value": "$.env.public_url"
      }
    },
  • "state": "active",
  • "signingKey": "ilYCCd7R40K1Ba9ra7k3VdKLKEUw9y9fvCiLEGGJdO/Gz73zqvR16IxUyZc3+ieGJsdfXz3Z0H8+ubb3wVtJLw=="
}

List Subscriptions

get/core/v1/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.

SecuritybearerAuth
Request
query Parameters
first
integer <int32>
Example: first=1
last
integer <int32>
Example: last=10
cursor
string
Example: cursor=slack25052023
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - Returns an elements array of all the trigger subscriptions and pageInfo for pagination

Response Schema: application/json
Array of objects (PublicConnectorEventsSubscription)
required
object (PublicPageInfo)
400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "elements": [
    • {
      • "id": "<uuid>",
      • "externalId": "<external_id>",
      • "publicUrl": "<public_url>",
      • "name": "<name_of_subscription>",
      • "trigger": {
        • "name": "slack-trigger",
        • "version": "7.0",
        • "operation": "events_api"
        },
      • "endpoints": {
        • "connectorEventEndpoint": "<endpoint_to_send_connector_events_to>",
        • "stateChangeEventEndpoint": "<endpoint_to_send_state_changes_to>"
        },
      • "state": "ACTIVE"
      },
    • {
      • "id": "<uuid>",
      • "externalId": "<external_id>",
      • "publicUrl": "<public_url>",
      • "name": "<name_of_subscription>",
      • "trigger": {
        • "name": "slack-trigger",
        • "version": "7.0",
        • "operation": "events_api"
        },
      • "endpoints": {
        • "connectorEventEndpoint": "<endpoint_to_send_connector_events_to>",
        • "stateChangeEventEndpoint": "<endpoint_to_send_state_changes_to>"
        },
      • "state": "CREATION_FAILED",
      • "errorMessage": "Subscription could not be created. Reason: <x>"
      }
    ],
  • "pageInfo": {
    • "startCursor": "<cursor_for_previous_page>",
    • "endCursor": "<cursor_for_next_page>",
    • "hasNextPage": true,
    • "hasPreviousPage": false
    }
}

Get Subscription

get/core/v1/subscriptions/{subscription-id}
This endpoint is non-billable.

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

SecuritybearerAuth
Request
path Parameters
subscription-id
required
string <uuid>
Example: 1a71daf1-XXXX-XXXX-XXXX-dbb4ab325a55
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - Returns a Subscription object

Response Schema: application/json
externalId
string

Unique ID of the Subscription on your end that you can use to query Subscriptions using Get Subscriptions

id
required
string

Unique ID of the Subscription on Tray's end

required
object (PublicConnectorEventsTriggerReference)

Reference to link the Trigger

state
required
string (SubscriptionState)

Indicated current state of the Subscription

Enum: "creating" "creation_failed" "deleted" "active"
object

Details about error if any in creating the subscription

authenticationId
string <uuid>

Unique id of the auth returned by Create Authentication

operation
required
string

Programmatic name of the Trigger operation. Obtained using Get Trigger operations

required
object

A JSON object that follows that input schema of the above operation returned by Get Trigger operations

name
required
string

Name of the Subscription e.g. Slack subscription USER_832782

endpoint
required
string

Your URL where Tray would post events

400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "id": "<uuid>",
  • "externalId": "<external_id>",
  • "publicUrl": "<public_url>",
  • "name": "<name_of_subscription>",
  • "trigger": {
    • "name": "slack-trigger",
    • "version": "7.0"
    },
  • "operation": "events_api",
  • "endpoint": "<endpoint_to_send_connector_events_to>",
  • "state": "active"
}

Delete Subscription

delete/core/v1/subscriptions/{subscription-id}
This endpoint is non-billable.

Deletes a subscription using subscription ID as the parameter.

SecuritybearerAuth
Request
path Parameters
subscription-id
required
string <uuid>
Example: 1a71daf1-XXXX-XXXX-XXXX-dbb4ab325a55
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
204

No content - The subscription was deleted successfully

400

Invalid Input

401

Unauthorized

403

Forbidden

404

Not Found

429

Limit Exceeded

500

Internal Error

Request samples
Response samples
text/html