Navigation

External Services

Introduction

Modern applications often use multiple external services to handle complex use cases such as messaging, analytics, and data management. Your Stitch application can securely interact with these external services and applications through a unified, semantic service API that encapsulates implementation details and enforces service rules that you define. There are two primary ways to interact with external services: service actions and incoming webhooks.

You can configure an interface for each external service that your app connects to. Stitch includes custom integrations for some services, such as Twilio and AWS, and a generic HTTP service for services that don’t have custom integrations.

Concepts

Service Actions

You can send requests to external services through service-specific client objects that you can access from functions and client SDKs. Service clients provide methods that handle common actions for their respective service, such as sending a text message with Twilio or putting an object to AWS S3. These methods, called service actions, encapsulate implementation details like request authentication and HTTP methods behind a semantic API that’s common across all Stitch services.

Whenever you call a service action, Stitch checks each service rule that applies to the action and prevents execution unless one of the rules evaluates to true. As a result, all service actions are disabled by default. You must define a service rule that enables a particular action before you can call it.

Service Rules

Service rules allow you to restrict the scope and capabilities of service actions in your application. Each service rule applies to one or more actions in the service and limits the scope of those actions by preventing execution unless the configurable JSON expression for the rule evaluates to true.

For example, you could create a Twilio rule that only lets users send a text message from a specific phone number or an AWS rule that prevents users from putting objects to an S3 bucket that is not included in a list of approved buckets.

Expression Variables

Expression variables are variables that you can include in service rules to represent dynamic information about your application and an action’s execution. You can configure service rules based on the authenticated user that called an action (%%user) and the arguments that they provided (%%args). You can also create complex rules that call a function (%function) and evaluate based on the function’s return value.

For detailed descriptions of the possible arguments a particular action can receive as well as rule templates that cover common use cases, see that action’s reference page.

Incoming Webhooks

Incoming webhooks are custom handlers for events that originate in an external service, such as a new GitHub pull request or a Twilio phone number receiving a text message. Each incoming webhook is associated with a particular service and consists of two primary components: the webhook URL and the webhook function.

Webhook URL

A URL that uniquely identifies the incoming webhook. Third parties can interact with the webhook by sending an HTTP request that matches the webhook’s configuration to the webhook URL.

To use a webhook, provide the webhook URL to an external service’s HTTP request handler, which may also be referred to as an outgoing webhook, callback URL, or similar.

Note

If an incoming webhook requires a secret query parameter, make sure that you append the query parameter to webhook URL before you provide it to the external service.

Webhook Function
A webhook function is a Stitch function that accepts an incoming HTTP request with data from the external service as its argument and optionally returns an HTTP response.

Get started with incoming webhooks by creating a service webhook.

Usage Guides

Guide Description
Create a Service Learn how to create a new external service interface.
Create a Service Webhook Learn how to configure and execute an incoming webhook to handle events in external services.
Define a Service Rule Learn how to safely expose a service action for use in a function or client application.
Call a Service Action Learn how to call a service action from a function or client application.
Send Mobile Push Notifications Learn how to send and manage push notifications for iOS and Android client applications.

Reference Documentation

Subject Description
Twilio Service Includes service configuration parameters, directions for adding a webhook to Twilio, and additional information about Twilio service actions.
HTTP Service Includes additional information about HTTP service actions and webhooks.
AWS Service Includes service configuration parameters, additional information about specifc AWS service actions, and generic directions for connecting to any AWS service.
GitHub Service Includes service configuration parameters, directions for adding a webhook to GitHub, and guidance on validating incoming requests from GitHub.
Push Notifications Includes service configuration parameters, arguments available in push notification rules, and directions for integrating push notifications into a mobile client.
Webhook Requests & Responses Describes how to verify incoming requests, parse a request payload, and send a response in service webhook functions.
JSON Expressions Describes how to construct and compose JSON expressions for use in service rules.
Expression Variables Includes descriptions and usage examples for variable values in JSON expressions, including service rules.