You specify:

  1. The URL of the web service.
  2. The HTTP verb.
  3. Optional header values. These often contain Authentication information such as a token or username/password.
  4. The precise format and content of the data sent to the web service.

URL: You must specify the URL for the HTTP request. 

The URL must be an absolute URL. 

The URL may include AppSheet expressions. The expression result will replace the expression in the URL.

If you are using the webhook to invoke the AppSheet API, you should enter the webhook URL value in the following form.

https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action

Where

  • {appId} specifies the GUID of the AppSheet application. You can obtain the {appId} from the Manage > Integrations > IN pane.
  • {tableName} specifies the name of the table.

While the app is in test mode (i.e. it has not passed a Deployment Check), the Webhook will not  be invoked.

HTTP Verb: You must specify the verb to be used for the HTTP request. 

  • Post (This is the default value, and by far the most common choice.)
  • Delete
  • Patch
  • Put

HTTP Headers: You can optionally specify one or more HTTP headers to be included with the HTTP request.

The most common HTTP Header is an Authentication header.

Each header must be specified on a separate line. Each header line must specify the header name, followed by a colon, followed by the header value.

The header name and header value may include constants or AppSheet expressions. The expression result will replace the expression in the HTTP header.

If the header value contains quote characters, you must enclose the entire header value within quotes, and escape each embedded quote with two quotes. For example, if the header name is Authorization  and the header value is Token token="537d7d", you should enter Authorization: "Token token=""537d7d""" in the header line.

For example, when invoking Pushpad from a webhook you might need to include the following header values:

Authorization: Token token="9474e7dfeffa2eb49e656b4ba7c96a06"
Accept: application/json

Do this by specify each of the header values on a separate line:

Authorization: "Token token=""9474e7dfeffa2eb49e656b4ba7c96a06"""
Accept: "application/json"

We automatically set the "Content-Type" header to the following value:

Content-Type: "application/json"

 

HTTP Operation
The HTTP Post, Delete, Patch, or Put operation is performed synchronously. 

The initial operation is performed with a timeout of 20 seconds. If the operation fails with a timeout error, the operation is retried up to 5 times. All retries are performed with a timeout of 40 seconds. The first retry is delayed by .4 seconds. Subsequent retries are delayed using exponential backoff delays of .9 seconds, 1.6 seconds, 2.5 seconds, and 3.6 seconds.

Body: You have three options when it comes to the body of the HTTP request. 

  1. You can specify nothing and receive a default HTTP body that contains all of the values from the updated row except for Hidden columns and Show type columns.
  2. You can specify a body in the Body field.
  3. You can specify a BodyTemplate as described below.

BodyTemplate: 

You can control the contents and format for your body by using a .txt file as a template file. We recommend using a JSON Body Template file if you wish to control the format of the body.

In your template file, you can include:

  1. Text
  2. Images
  3. Variables that refer to column values in your tables
  4. Expressions that yield computed values

After the variables and expressions are replaced, the template becomes the body. When a JSON Body Template file is present, it is used in lieu of the “Body”.

Creating a JSON Body Template File

To create a JSON Body Template file, click the Create button to the right of "JSON Body Template". This will create a default JSON Body Template file that displays the data values from your table. 

If you are using the webhook to invoke the AppSheet API, you should enter the webhook URL value, as described above, before clicking the Create button. We examine the webhook URL value to determine if the AppSheet API is being invoked. If so, we use the table name you specify following "/tables/" in the URL to determine the field values to include in the JSON body template.

If your table contains a List of Refs to related child records, the created JSON Body Template file will include a Start expression that extracts the data values of all child records of the parent record. 

If the child table contains a List of Refs to related grandchild records, the created JSON Body Template file will include a Start expression that extracts the data values of all grandchild records of the child records. 

The created JSON Body Template file will extract the parent record, the child records, the grandchild records, the great grandchild records, and so on. This allow you to extract the entire hierarchy of records.

Once the JSON Body Template file is created, click the View button to view the template.

We currently only support JSON Body Template files stored on Google Drive and the JSON Body Template file must be either a .txt or .json file. If you wish to specify a JSON Body Template file, you must include Google as a data provider. If Google is not already a data provider, you must go to Account>Data Sources and add Google as a data provider.

The JSON Body Template always refers to a single Google template file. You cannot use an expression to specify the name of the JSON Body Template file. If you need to choose between Google template files, define a separate workflow rule for each template file and specify an expression in the "Condition" property to select which workflow rule to invoke.

Manually Editing the JSON Body Template File

You can edit the JSON Body Template file by:

  1. Downloading the current template file from Google Drive.
  2. Editing the template file using a text editor.
  3. Uploading the updated template file to Google Drive.
  4. Ensuring the Editor is referring to the latest template file.



Downloading the template file from Google Drive

  1. Go to the Account>Setting pane in the Editor and find the "Default folder path".
  2. In Google Drive, locate the "Default folder".
  3. Withing the "Default folder", locate the folder containing your app.
  4. Within the folder containing your app, locate the  "Context" folder.
  5. Right click the template .txt file and select "Download". This will down load the template file to your local computer.

You can then edit the template file. Once the template file is edited you can upload the template file to Google Drive as follows.

Uploading the template file to Google Drive

  1. Open Google Drive and navigate to the "Content" folder on Google Drive as described in "To Download the template file from Google Drive". 
  2. Click the "New" button and then click "File upload". 
  3. When the file open dialog appears, navigate to the template file on your personal computer, select the file, and click "Open". This will upload the template file to Google Drive.

After Uploading the template file to Google Drive

  1. Open the AppSheet Editor and go to the appropriate Workflow or Report.
  2. Click the file icon for the "JSON Body Template" field. 
  3. When the "Select a file" dialog appears, navigate to the uploaded template file you uploaded to Google Drive and select it.
  4. This makes the uploaded template file the current JSON Body Template.

Each time you modify the template you must upload the template file to Google Drive. Google Drive will retain the original DocId. AppSheet will use the newly uploaded template file thereafter.

Manually Creating a JSON Body Template File

You can manually create a JSON Body Template file by creating an empty .txt or .json file on your personal computer, entering JSON text like that below, and saving the file to your personal computer.

{
    "Action": "Edit",
   "Properties": {
      "Locale": "en-US",
      "Location": "47.623098, -122.330184",
      "Timezone": "Pacific Standard Time"
   },
  "Rows": [
   {
      "Name": "<<Name>>",
      "Qty": "<<[Qty]>>",
      "Price": "<<[Price]>>",
      "Total": "<<[Qty]*[Price]>>",
      "Sales Tax": "<<[Qty]*[Price]*0.085>>",
      "Email": "<<[Email]>>",
      "Product Image": "<<[Product Image]>>",
   }
 ]
}


Once the template file is saved to you personal computer, you can upload it to Google Drive by following the steps in:

  1. Uploading the template file to Google Drive
  2. After Uploading the template file to Google Drive

Creating a JSON Body Template File with <<Start>> and <<End>> Tags

Your template file can contain <<Start>> and <<End>> tags. This will repeat the JSON values between the <<Start>> and <<End>> tags for each row returned by the <<Start>> expression.

{
   "Action": "Edit",
   "Properties": {
      "Locale": "en-US",
      "Location": "47.623098, -122.330184",
      "Timezone": "Pacific Standard Time"
   },
  "Rows": [
    <<Start: Filter(OrderDetails, true)>>
    {
      "Name": "<<Name>>",
      "Qty": "<<[Qty]>>",
      "Price": "<<[Price]>>",
      "Total": "<<[Qty]*[Price]>>",
      "Sales Tax": "<<[Qty]*[Price]*0.085>>",
      "Email": "<<[Email]>>",
      "Product Image": "<<[Product Image]>>"
    },
    <<End>>
  ]
}

Creating a JSON Body Template File with <<If>> and <<EndIf>> Tags

Your template file can contain <<If>> and <<EndIf>> tags. This will conditionally include the JSON values between the <<If>> and <<EndIf>> tags . In the following example, field Sales Tax is included if Total is $1.00 or more.

{
   "Action": "Edit",
   "Properties": {
      "Locale": "en-US",
      "Location": "47.623098, -122.330184",
      "Timezone": "Pacific Standard Time"
   },
  "Rows": [
    <<Start: Filter(OrderDetails, true)>>
    {
      "Name": "<<[Name]>>",
      "Qty": "<<[Qty]>>",
      "Price": "<<[Price]>>",
      "Total": "<<[Qty]*[Price]>>",
      <<If: [Qty]*[Price] >= 1.00>>
      "Sales Tax": "<<[Qty]*[Price]*0.085>>",
      <<EndIf>>
      "Email": "<<[Email]>>",
      "Product Image": "<<[Product Image]>>"
    },
    <<End>>
  ]
}

Run Asynchronously

You can use the Run Asynchronously option to control whether the webhook is invoked synchronously or asynchronously. Invoking the webhook asynchronously can improve client response time when the webhook is invoked from a workflow rule. 

When you specify Run Asynchronously "On", the server invokes the webhook Post call but it does not wait for the webhook Post call to finish. As a result, the webhook Post call's response time is not included in the overall client response time.

When you specify Run Asynchronously "Off", the server invokes the webhook Post call and waits for the webhook Post call to finish. As a result, the webhook Post call's response time is included in the overall client response time.

Before you specify Run Asynchronously "On", consider whether your application requires the webhook to complete synchronously for correctness. If your webhook is changing data and your application relies on that data being updated before the sync completes, then using an asynchronous call may yield incorrect results.

Test and Troubleshooting your WebHook

See this article.

Did this answer your question?