This is a paid bot, and its usage will be counted toward your plan's credits limit. For more information about credit usage, refer to this article.
General
Install and configure the Send webhook on documents opening bot to send a webhook when a contract, invoice, or other document is opened. The bot gathers data, formats it in JSON format, and transfers it to the selected URL based on the ‘if-this-then-that’ conditions you set.
Installation
1. Hover over the step you intend to automate and select the +Add Bot to Step option.
2. Find the Send webhook on documents open bot and click Install bot to add the bot to your workflow.
3. In the infobox, you’ll find the Authorization token, which you will need for all API requests related to this bot.
Copy it and paste it as the Authorization header value in Postman or any other console of your choice.
{*Note: The slate_addons will have a single token within different workflow versions. Using this token, users will be able to access the data from all slate_addons and different workflow versions.
The bot operates within versioning. If the versioning doesn’t display, it means that your workflow only has one version by default that is always up to date. Versioning will become available right after you create another workflow version.*}
4. Configure the bot execution conditions and advanced settings as needed.
Conditions
Configure the bot execution conditions based on simple “if-this-then-that” rules. For example, you can set conditions based on document field information, recipient data, date of document signing, document data, and decline reason. Learn how to set up conditions that will activate the bot here.
Advanced settings
In this section, you can set additional bot configurations:
Determine how often the bot will run
Decide what to do with a revision if the bot fails
Add tags to your document to easily locate it
Learn more about adjusting Advanced settings in this article.
Once ready, click Apply.
Make a request to subscribe for document opening events
Use the POST /webhook-bot/v2/subscription endpoint to subscribe for document opening events.
Request example:
curl
--request POST \
--url ' https://bots.airslate.com/webhook-bot/v2/subscription' \
--header 'Authorization: {{authorization_token}}' \
--header 'Content-Type: text/plain' \
--data-raw '{
"data": {
"type": "subscriptions",
"attributes": {
"callback_url": " https://automation.pdffillers.com/report/whprefill"
}
}
}'
bots.airslate.com— the hostname that should be used in subsequent requests for US-based services.
bots.airslate-au.com — the hostname that should be used in subsequent requests for AU-based services.
Example:
POST https://bots.airslate-au.com/webhook-bot/v2/subscription
callback_url — the service URL that will receive webhooks.
Response example:
{
"data": {
"type": "subscriptions",
"id": "A88CB620-0000-0000-00002D5D",
"attributes": {
"callback_url": " https://automation.pdffillers.com/report/whprefill"
},
"relationships": {
"slates": {
"data": {
"type": "slates",
"id": "B2D12859-9300-0000-0000BA29"
}
},
"slate_addons": {
"data": {
"type": "slate_addons",
"id": "51131C22-A700-0000-000093F0"
}
},
"flow_revisions": {
"data": {
"type": "flow_revisions",
"id": "6602784C-9300-0000-000049B7"
}
}
}
data.id | The unique subscription identifier. |
slates.data.type | The ‘slates’ value of this attribute means that the slates.data object describes the attributes of a particular workflow. |
slates.data.id | The unique document identifier. As a bot user, you are subscribed to document opening events from this workflow. |
flow_revisions.data.type | The ‘flow_revisions’ value of this attribute means that the flow_revisions.data object describes the attributes of a particular document revision. |
flow_revisions.data.id | The unique document revision identifier. |
slate_addons.data.type | The ‘slate_addons’ value of this attribute means that the slate_addons.data object describes the attributes of a bot that is set up for a particular workflow version, not a document. |
slate_addons.data.id | The unique identifier of a bot setup in a particular workflow version. |
Status code of the response:
200 — the request was received. The response body will contain the subscription information such as subscription, workflow, and bot IDs.
400 — the request failed due to incorrect input parameters. Verify the request body. It might be missing or its attributes’ values are wrong.
401 — the request failed due to authorization issues. Verify the Authorization header. It might be missing or its value is wrong. Ensure the Authorization token matches your request token and resend the request.
403 — the request is forbidden since the bot was disabled. Enable the bot and resend the request.
Webhook response
Every time the bot is triggered by running a workflow or creating a revision, a webhook that contains the data needed to get a specific document is sent in a POST request to the {callback_url} of your service.
flow_id — the unique workflow identifier where a document was opened, or a revision created.
slate_addon_id — the unique identifier of the bot setup in a particular workflow.
slate_id — the unique identifier of the opened document.
revision_id — the unique identifier of the opened document revision.
organization_id — the unique identifier of your workspace.
{*Note: If the service is currently unavailable or the response code to the webhook request is not 200, the bot will try to send the webhook three times at one-hour intervals. You can always check the status of the webhook in the bots log section.*}
Webhook requests
Fetch
Send a GET request to the /webhook-bot/fetch endpoint to retrieve every document from all workflows and their versions for which the bot has sent webhooks. You can also filter the documents by a particular document ID/ revision ID/ workflow version ID. The response body will contain a list of filtered documents, their fields, and an extended list of the fields’ attributes.
Request example:
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/v2/fetch?filter [slate_id]={slate_id_1}&filter [revision_id]={revision_id_1}' \
--header 'Authorization: {{authorization_token}}'
Request parameters:
filter [slate_id] — the request parameter which allows for filtering documents by a specific document ID — {slate_id_1}.
filter [revision_id] — the request parameter which allows for filtering documents by a specific revision ID — {revision_id_1}.
filter [flow_revision_id] — the request parameter which allows for filtering documents by a specific workflow version ID — {flow_revision_id_1}.
Status code of the response:
200 — the request was received. The response body will contain a list of filtered documents, their fields, and an extended list of the fields’ attributes.
401 — the request failed due to authorization issues. Verify the Authorization header. It might be missing or its value is wrong. Ensure the Authorization token matches your request token and resend the request.
The response body will display the list of filtered documents, their fields, and the extended list of fields' attributes.
Subscription
Send a GET request to the /webhook-bot/v2/subscription endpoint to review the active subscriptions of the bot.
Request example:
curl
--request GET \
--url 'https://bots.airslate.com/webhook-bot/v2/subscription' \
--header 'Authorization: {{authorization_token}}'
Response example:
{
"data":[ {
"type":"subscriptions",
"id":"00B43310-0000-0000-00002D5D",
"attributes":{
"callback_url":"{callback_url}"
},
"relationships":{
"slates":{
"data":{
"Type":"slates",
"id":"4404E192-C200-0000-0000BA29"
}
},
"slate_addons":{
"data":{
"type":"slate_addons",
"id":"87DC5CD5-3500-0000-000093F0"
}
},
"flow_revisions": {
"data": {
"type": "flow_revisions",
"id": "4BDA29C6-7100-0000-000049B7"
}
}
]
}
Response body parameters:
data.id | The unique subscription identifier. |
slates.data.type | The ‘slates’ value of this attribute means that the slates.data object describes the attributes of the particular workflow. |
slates.data.id | The unique workflow identifier. You, as a bot user, have subscribed to document opening events from this workflow. |
flow_revisions.data.type | The ‘flow_revisions’ value of this attribute means that the flow_revisions.data object describes the attributes of a particular workflow version. |
flow_revisions.data.id | The unique workflow version identifier. |
slate_addons.data.type | The ‘slate_addons’ value of this attribute means that the slate_addons.data object describes the attributes of a bot that is set up for a particular workflow, not a document. |
slate_addons.data.id | The unique identifier of a bot set up in a particular workflow version. |
Status code of the response:
200 — the request was received. The response body will contain the subscription data: subscription ID (data.id), callback URL (data.callback_url), workflow ID (slates.data.id), and bot ID (slate_addons.data.id).
401 — the request failed due to authorization issues. Verify the Authorization header. It might be missing or its value is wrong. Ensure the Authorization token matches your request token and resend the request.
Delete
To unsubscribe, send the DELETE request to the /webhook-bot/v2/subscription/{subscription_id} endpoint.
Request example:
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/v2/subscription/{subscription_id}' \
--header 'Authorization: {{authorization_token}}'
subscription_id — value of the data.id attribute from the subscription response body.
Response body: No response body
Status code of the response:
204 — the request was received and processed by the service. You have unsubscribed from receiving webhooks.
400 — the request failed due to incorrect input parameters. Verify the {subscription_id}. It might be missing or its value is wrong.
Statistics
Retrieve a list of webhooks sent by the bot by sending the GET request to the /webhook-bot/stats endpoint.
Request example:
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/stats \
--header 'Authorization: {{authorization_token}}'
The response example:
Status code: 200
Response body:
[
{
"slate_id": "C4D64766-6000-0000-0000C9C1", "revision_id": "3BEC3F61-8000-0000-00005363", "flow_revision_id": "4BDA29C6-7100-0000-000049B7","webhooks": [
{
"notified_at": 1578919682,
"status": "success"
}
]
},
{
"slate_id": "C86D5866-6000-0000-0000C9C1", "revision_id": "011AB071-8000-0000-00005363", "flow_revision_id": "4BDA29C6-7100-0000-000049B7","webhooks": [
{
"notified_at": 1578920763,
"status": "success"
}
]
}
]
Send the GET request to the /webhook-bot/stats endpoint with the corresponding request parameters to retrieve the list of webhooks sent by the bot and filtered by a document ID/revision ID/workflow version ID.
Request examples:
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/stats?filter [revision_ids]={revision_id_1},{revision_ id_2} \
--header 'Authorization: {{authorization_token}}'
OR
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/stats?filter [slate_ids]={slate_id_1},{slate_id_2} \
--header 'Authorization: {{authorization_token}}'
OR
curl
--request GET \
--url ' https://bots.airslate.com/webhook-bot/stats?filter [flow_revision_ids]={flow_revision_id_1}, {flow_revision_id_2} \
--header 'Authorization: {{authorization_token}}'
OR
curl
--request GET \
--url ' https://bots.airslate.com/v2/stats?filter [slate_ids]={slate_id_1}&filter [revision_ids]={rev ision_id_1}&filter [flow_revision_ids]={flow_revision_id_1} \
--header 'Authorization: {{authorization_token}}'
Request parameters:
filter [slate_ids] — the request parameter which allows for filtering webhooks by specified Flow ID — {slate_id_1}.
filter [revision_ids] — the request parameter which allows for filtering webhooks by a specific Revision ID — {revision_id_1}.
filter [flow_revision_ids] — the request parameter which allows for filtering webhooks by a specific Template Revision ID — {flow_revision_id_1}.
Code examples
Find below the PHP and Node.js code examples for the requests described above.
PHP code
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => ' https://bots.airslate.com/', 'headers' =>['Authorization' => 'your-token']]);
$url = '/webhook-bot/v2/subscription';
$statsUrl = '/webhook-bot/stats';
$body = ["data" => ["type" => "subscriptions", "attributes" => ["callback_url" =>
' https://your-callback-url']]];
// Add new subscription
$subscribeResponse = $client->post($url, ['json' => $body]);
// Review subscriptions
$viewResponse = $client->get($url);
echo $viewResponse->getBody()
->getContents();
// Unsubscribe
$id = json_decode($subscribeResponse->getBody()->getContents() , true) ['data']['id'];
$client->delete($url . '/' . $id);
// Review webhook statistics
$statsResponse = $client->get($statsUrl);
echo $statsResponse->getBody() ->getContents();
You can also find the code in this article.
Node.js code
const https = require('https');
// Add new subscription
const subscribeReq = https.request({
hostname: ' bots.airslate.com',
path: '/webhook-bot/v2/subscription',
method: 'POST',
headers: {
Authorization:'your-token'
}
},
res => {
res.on('data', d => process.stdout.write(d))
}
);
const data = new TextEncoder().encode(
JSON.stringify({
data: {
type: 'subscriptions',
attributes: {
callback_url: ' https://your-callback-url-t'
}
}
})
);
subscribeReq.write(data); subscribeReq.end();
// Review subscriptions
const viewReq = https.request({
hostname: ' bots.airslate.com',
path: '/webhook-bot/v2/subscription',
method: 'GET',
headers: {
Authorization: 'your-token'
}
},
res => {
res.on('data', d => process.stdout.write(d))
}
);
viewReq.end();
// Unsubscribe
const deleteReq = https.request({
hostname: ' bots.airslate.com',
path: '/webhook-bot/v2/subscription/{UID}',
method: 'DELETE',
headers: {
Authorization: 'your-token'
}
},
res => {
res.on('data', d => process.stdout.write(d))
}
);
deleteReq.end();
// Review webhook statistics
const statsReq = https.request({
hostname: ' bots.airslate.com',
path: '/webhook-bot/v2/stats',
method: 'GET',
headers: {
Authorization: 'your-token'
}
},
res => {
res.on('data', d => process.stdout.write(d))
}
);
statsReq.end();
You can also find the code in this article.