Create a Cloud App template

Use this endpoint to create a Cloud App template.

API at a glance

Description: This API creates a Cloud App template in your Blueshift account. You set the endpoint that Blueshift calls, the HTTP method, the request content, headers and authentication. You can link the template to a Cloud App, or leave it out to create a Custom JSON template.

Authentication & testing

Testing the API on this page

How to try it here

  • Use your User API Key as the Username (leave Password blank).
  • Select the appropriate API endpoint based on your Blueshift region.
  • API - Select Region
  • Enter the necessary parameters and click Try It to run the request.
Authentication using Base64 encoding

Note for developers

API requests require authentication using HTTP Basic Authentication with an API key. The API key serves as the username, while the password field should be left empty. The format to encode is: your_api_key: (note the trailing colon).

This string must be Base64-encoded and included in the request's Authorization header as follows:

Authorization: Basic encoded_value

You can generate the encoded value using a trusted Base64 encoder.


Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.


Things to know before you start

  • API key: Use your User API key.
  • Cloud Apps: Cloud Apps must be enabled for your account. Otherwise, the API returns 403.
  • Required fields: name, resource.external_webhook_url, resource.http_method and resource.content.
  • Unique name: The name must be unique among your account's Cloud App templates. Names aren't case-sensitive.
  • Content: content must be valid JSON. It can contain Liquid, such as {{user.email}}. Blueshift checks the JSON with Liquid filled in as empty values, so put Liquid inside quotes: "age": "{{user.age}}", not "age": {{user.age}}.
  • Authentication: Send auth_header and auth_token together, or leave both out. Each can be up to 200 characters. When you send them, external_webhook_url must start with https:// or with Liquid.
  • Auth token: auth_token is never returned. Responses show ***.
  • Author: Send author with the email address of an active user in your account. If you leave it out, or the email doesn't match an active user, the account's primary user becomes the author.
  • Cloud App: app_uuid must be a Cloud App your account can use. You can't change it after you create the template.
  • Copying an auth token: To copy an existing Cloud App template's auth token, send clone_id with its UUID and set resource.auth_token to ***. If no Cloud App template in your account has that UUID, the API returns 422. Without ***, clone_id is ignored.
  • External fetches and transaction mixins: Send them as objects with a uuid. UUIDs that don't match an external fetch or segment are ignored.
  • Recommendations: account_algorithm_uuid must be an active recommendation scheme in your account. To set skip_on_all_blank_recommendation_blocks to true, also send skip_user_on_blank_products: false.
  • Not available through the API: deleting, previewing and test-sending a template. Use the Blueshift app for these.
  • Use case: Best for creating Cloud App templates from your own tools and scripts.

Request parameters

Check out the request parameters

Body parameters

ParameterTypeRequiredDescription
namestring✅ YesName of the template.
resourceobject✅ YesThe request that Blueshift sends. See structure below.
authorstring❌ NoEmail address of the template's author.
tag_datastring❌ NoFolder and tags, in the format folder_name:tag1,tag2. Separate folders with |. The folder must already exist in your account. If the folder has a list of allowed tags, each tag must be on it. Otherwise, the API returns 422.
skip_user_on_external_fetch_errorboolean❌ NoIf true, Blueshift doesn't send the request for a customer when an external fetch fails.
external_fetchesarray❌ NoExternal fetches to use, as objects with a uuid. For example, [{"uuid": "<external fetch UUID>"}].
transaction_mixinsarray❌ NoTransaction mixins to use, as objects with a uuid.
template_propertiesobject❌ NoRecommendation settings. Keys: account_algorithm_uuid (an active recommendation scheme in your account; null removes it), skip_user_on_blank_products (default true), skip_user_on_blank_event_products (default true) and skip_on_all_blank_recommendation_blocks (default false). skip_user_on_blank_products and skip_on_all_blank_recommendation_blocks can't both be true. Responses return this as an array.
clone_idstring❌ NoUUID of another Cloud App template in your account. Send it with resource.auth_token set to *** to copy that template's auth token into the new template.

Resource object

ParameterTypeRequiredDescription
external_webhook_urlstring✅ YesThe endpoint Blueshift calls. Starts with http:// or https://, or with Liquid.
http_methodstring✅ YesPOST, PUT, PATCH or GET.
contentstring✅ YesRequest content as a JSON string. Can contain Liquid.
headersobject❌ NoHTTP headers to send, as key-value pairs.
auth_headerstring❌ NoName of the authentication header, for example Authorization.
auth_tokenstring❌ NoValue of the authentication header.
app_uuidstring❌ NoUUID of the Cloud App this template uses. Leave it out for a Custom JSON template.
account_app_profile_uuidstring❌ NoUUID of an enabled Cloud App connection in your account. If you set it, Blueshift uses the connection's authentication instead of auth_header and auth_token.
contextstring❌ NoA sample event as a JSON string, used when you preview or test the template in the Blueshift app.
is_url_encoded_formboolean❌ NoIf true, Blueshift sends the content as a URL-encoded form.
dedupe_fieldstring❌ NoName of a customer attribute that identifies each customer for this template (Unique Sent Identifier in the Blueshift app). Blueshift doesn't send the request for customers who don't have this attribute.
use_json_editorboolean❌ NoIf true, the template opens in the JSON editor in the Blueshift app. If false (default), it opens in the form editor.
content_metadataobject❌ NoField layout for the form editor in the Blueshift app.

Example requests & responses

Create a Custom JSON template

Request

curl --request POST \
     --url 'https://api.getblueshift.com/api/v1/webhook_templates.json' \
     --header 'accept: application/json' \
     --header 'authorization: Basic <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '{
       "name": "Order confirmation webhook",
       "resource": {
         "external_webhook_url": "https://example.com/orders",
         "http_method": "POST",
         "content": "{ \"email\": \"{{user.email}}\" }"
       }
     }'

Response

{
  "name": "Order confirmation webhook",
  "created_at": "2026-11-19T05:53:43.140Z",
  "updated_at": "2026-11-19T05:53:43.140Z",
  "uuid": "75f48ce5-7955-48d9-a06d-88732b1b079f",
  "skip_user_on_external_fetch_error": null,
  "archived": false,
  "author": "Jane Doe",
  "template_properties": [],
  "tag_data": "",
  "external_fetches": [],
  "transaction_mixins": [],
  "resource": {
    "auth_header": null,
    "http_method": "POST",
    "external_webhook_url": "https://example.com/orders",
    "content": "{ \"email\": \"{{user.email}}\" }",
    "dedupe_field": null,
    "context": null,
    "is_url_encoded_form": false,
    "headers": null,
    "content_metadata": null,
    "use_json_editor": false,
    "auth_token": null,
    "app_uuid": null,
    "account_app_profile_uuid": null,
    "app_name": null
  }
}
Unknown Cloud App

Response (422)

{
  "errors": [
    {
      "detail": "Cannot find cloud app with uuid=00000000-0000-0000-0000-000000000000"
    }
  ],
  "meta": {
    "combine_errors": false,
    "no_toast": false
  }
}
Body Params
string
required

Unique among your Cloud App templates (not case-sensitive).

string

UUID of another Cloud App template in your account. With resource.auth_token set to ***, copies that template's auth token. Ignored otherwise.

string

Email of an active user in your account. Otherwise the account's primary user is the author.

string

Folder and tags, in the format folder_name:tag1,tag2. Separate folders with |. The folder must already exist. On update, replaces all the template's tags.

boolean

If true, Blueshift doesn't send the request for a customer when an external fetch fails.

external_fetches
array of objects
external_fetches
transaction_mixins
array of objects
transaction_mixins
template_properties
object

Recommendation settings. Returned as an array in responses.

resource
object
required
Responses

Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json