Remote API

Welcome to the documentation for the Sequence Remote API! This guide will provide you with all the information you need to integrate and utilize the new Remote API feature in Sequence.

Important!

Remote API is a beta feature and needs to be enabled. If you are interested in using the feature, please email support@getsequence.io.

1. Introduction

What is the Sequence Remote API?

The Sequence Remote API is a powerful feature that enables developers to interact with Sequence's services programmatically from external applications. It allows you to trigger rules externally, or decide the amount to be transferred for any given rule using simple HTTP requests.

Key Benefits

- Connectivity: Connect Sequence to any external service or application.
- Flexibility: Seamlessly incorporate Sequence functionality into your existing workflows.
- Personalization: Use your own calculations for deciding how much money should be transferred.

2. Remote API types

The Sequence Remote API offers 2 types of endpoints to interact with various features. Each endpoint has specific functionalities, parameters, and responses.

Trigger

Description

Remote API Trigger opens the option for the triggering of rules from an external service by sending an http request to a url that is automatically generated at the time of the rule's creation.

Usage:

1. Log in to your Sequence account

2. When creating a rule select the type of trigger: Triggered remote API

3. Select the type of action and amount and click on: "Save"

4. Sequence will generate a URL Address and a Secret

5. Any request sent to the generated URL will trigger the rule

Security:

Implementing external triggers for Sequence rules is sensitive and is secured by a secret key. Once a trigger URL is generated, the system concurrently produces a secret key. This key must be included in every HTTP request to fulfill authentication criteria and successfully initiate the designated rule. The secret key should be added as a bearer token for the request header named "x-sequence-signature'.

Idempotency:

Our API operations support request idempotency, allowing you to call a sensitive operation multiple times and assume that its work will be done no more than once. You may use any string of up to 255 characters as a idempotency-key value (we recommend UUID version 4).

The guarantee of idempotency is crucial when an API call has failed without a clear reason and a retry is due. For example, if creating a payment does not succeed due to a network error, you can safely retry creating the payment, passing the same idempotency-key and assume the payment will occur no more than once, regardless of the number of calls.

Example Request:

curl --request POST
--url http://app.sequence.io/api/remote-api/rules/59ab175c-0913-4ea4-9876-5918990198d6/trigger
--header 'x-sequence-signature: Bearer 46b9f04a-5437-404a-914f-a2a622731bd0'
--header 'idempotency-key: 63d46d6e-16dd-4489-81d3-17c8ffc95c45'
--header 'content-type: application/json'
--data '{}'

Example Response:

{ 
 "code": "OK",
 "message": "...",
 "data": 
   { 
     "requestId": "uuid" 
   }
}

Action

Description

The Remote API Action feature enables Sequence to delegate the control over transfer amounts to an external service. Whenever Sequence executes a rule containing a "Remote API Action," it initiates an HTTP request to a pre-configured remote URL. In return, it expects to receive an amount value from the remote service. Sequence then utilizes this received amount for executing the transfer.

Usage:

1. Log in to your Sequence account

2. When creating a rule select the type of action: Query Remote API 

3. Enter the url of your external service and click Save.

5. Sequence will send a POST request to the remote service whenever the rule runs.

Example Response (From external service):

{
"amountInCents": 25000
}

Security:

To allow the external service to validate that the request is indeed coming from Sequence, Sequence will generate a unique signature that it will send with the request. The unique token will be generated and displayed once the user saves the rule.

The signature will be added as a header and will look like this (example): 

x-sequence-signature: "Bearer 0f5d8593-2d32-40ec-a9d9-cb122ea95044"