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": {
        • "$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"
        ]
      }
    ]
}
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. 
        
  2. Events where Tray attempted delivery but your endpoint doesn't respond after retries
    3. 
        
  3. Events which you filter out at the connector level e.g. applying a filter condition using pick val on salesforce 'on record create'.
    4. 
    

    

        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"
    },
  • "endpoint": "https://9e2cf626-c0b6-4764-884a-b7bf33200b41.trayapp.io"
}
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