Create a Shopify Flow action
Connect your app to Shopify Flow, so that your app receives data and information when a workflow action runs.
To create an action that your merchants can use in their workflows, you need to add the action to your app. Your action needs to contain the following information:
- the fields that the merchant needs to complete when they add your action to their workflows
- the URL that Shopify Flow needs to use to send (POST) the contents (JSON payload) of the action to your app
You also need to configure your app to process the data from the HTTP request (POST) when it arrives and to send status codes back to Shopify Flow.
Guidelines
Keep the following information in mind when you create your actions.
HTTP status codes and retry exceptions
After Shopify Flow sends an HTTP request (POST) to your web server, it waits for a maximum of 10 seconds for an HTTP status code.
If after 10 seconds Shopify Flow hasn't received a response from your web server, then it closes the connection to your web server and it resends the request at a later time.
When Shopify Flow receives a response, it processes the codes as follows:
Status codes | How Shopify Flow processes them |
---|---|
200 Success | Shopify Flow assumes that the POST request has been processed by your web server. |
202 Success | Shopify Flow assumes that the POST request has been accepted but not processed by your web server. Shopify Flow will resend the HTTP request (POST) at increasing intervals for up to 24 hours. |
4XX Client errors |
If your web server sends a 429 (too many requests) status code without a Retry-After header, then Shopify Flow resends the HTTP request (POST) at increasing intervals for up to 24 hours. If your web server sends a 429 (too many requests) status code with a Retry-After header (that specifies a wait time), then Shopify Flow resends the HTTP request (POST) after the wait time (formatted in seconds) has passed.
If your web server sends any other 4XX code, then Shopify Flow assumes that there was a failure and it does not resend the POST request. Your merchants will see a notification in Shopify Flow that includes the raw contents of your web server's response (for example,
|
5XX Server errors | Shopify Flow resends the HTTP request (POST) at increasing intervals for up to 24 hours. |
Other status code | If your web server returns a code that isn't described in this table, then Shopify Plus assumes that there was a failure and it does not resend the POST request. |
Prevent apps from processing duplicate requests
Each request from Shopify Flow contains an action_run_id
, which is unique to the associated action run (not to the request). This ID is included in the body of the request. You can use this action_run_id
to check if the request is unique.
In some cases, your app could receive the identical request more than once. For example, Shopify Flow might resend a request because it didn't receive your response in time.
Identify your actions
When you create an action, an action_definition_id
is assigned to it.
You can find an action's action_definition_id
in its Payload preview in the Partner Dashboard. For example:
{
"shop_id": 0,
"shopify_domain": "johns-apparel.myshopify.com",
"action_run_id": "xxxx-xxxx-xxxx-xxxx",
"action_definition_id": "Log weather changes",
"properties": {}
}
The action_definition_id
is sent as part of the payload when your action is run. When your web server receives a request, verify that the action_definition_id
matches the ID of an action that you created. If you have created multiple actions, then you can also use the action_definition_id
to sort the payload contents for processing in your web server or application.
Before you begin
Make sure that you have the following:
- A test web server that has access to the Internet, so that it can receive POSTs from Shopify Flow.
- A test app that works with the test web server.
- A test store that has Shopify Flow and the test app installed.
Step 1: Add an action for Shopify Flow (Shopify Partner Dashboard)
The example used in this task creates an action that saves weather information (city and temperature) to a web server.
- In the Shopify Partner Dashboard, open the Shopify Flow app extension:
- Click Apps and then open your test app.
- Click Extensions and then click Flow.
- Click Add action.
- Enter a title and description for your action. For example, enter
Log weather
andSave a log of the weather changes
respectively. In the Action Preview area, you can see how the title and action will appear to your merchants when they are choosing actions in Shopify Flow. - Enter the URL where the JSON payload will be sent to your web server.
Click Create field, choose a data type, and create the fields that will appear in Shopify Flow when your merchant chooses your app action. For example, create two fields that contain the following values.
Field 1 - Data type:
Short Text
- Field name:
Location
- Label:
Location of weather change
- Help text (optional):
Enter {{trigger.location}} to automatically populate the city.
Field 2 - Data type:
Number
- Field name:
Temperature
- Label:
Temperature in Fahrenheit (rounded to the nearest whole number)
- Help text (optional):
Enter {{trigger.temperature}} to automatically populate the temperature.
- Data type:
Click Save.
Step 2: Add support for your action in your web server
After you create your action in the Partner Dashboard, you need to add a service to your web server to listen for the JSON payload that Shopify Flow will send when your action runs.
For security reasons, your web service should enforce a hash-based message authentication (HMAC) header verification that uses the API secret key that you created when you configured your app. The HMAC header that you need is located in the following header: x-shopify-hmac-sha256
. If you are using a Ruby-based web framework, the header will be http-x-shopify-hmac-sha256
.
When your action runs in a workflow, Shopify Flow posts the contents (JSON payload and the HMAC header) of the action to the URL that you entered when you created the action in the Partner Dashboard. When your web server receives the POST request, it needs to verify the HMAC header (x-shopify-hmac-sha256
or http-x-shopify-hmac-sha256
for Ruby-based web frameworks) against the JSON payload (from the post) and your API secret.
Your web server also needs to verify that the action_definition_id
that is sent in the payload matches the ID of an action that you created.
After you've verified the HMAC header, you can process the contents of the payload. For example, you could log the contents of the payload to your web server's console.
Step 3: Test your action in a workflow
Now that you’ve created an acton in the Partner Dashboard and added support for it in your web server, you can test it in Shopify Flow. In your test store, create a workflow that uses the action that you created for your app.
In your test store, create a workflow that uses your action. For example, add the Weather changes trigger that you created in the Create Shopify Flow Triggers topic and this action to a workflow.
Trigger the workflow. For example, in your web server run the event that sends the trigger information to Shopify Flow.
When this workflow completes, your web server will have sent weather information to Shopify Flow and Shopify Flow will have sent this weather information to a web server that will log the information to its console.