Send webhook on documents completion bot

1. To add the bot to your workflow, select where you’d like to put it on the diagram and click the plus icon and select Bot from the menu.

2. Find the Send webhook on documents completion bot and click Install bot to add it 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.

In this section, you can set additional bot configurations:

Learn more about adjusting Advanced settings in this article.

Once ready, click Apply.

Use the POST /webhook-bot/v2/subscription endpoint to subscribe for document completion 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"
}
}
}

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.

Every time the bot is triggered (when an airSlate user completes documents), a webhook that contains the data needed to get a completed document, will be 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.*}

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.

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:

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.

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.

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}.

Find below the PHP and Node.js code examples for the requests described above.

<?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.

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.