From 0ddb897118296394313e420c61f1b9124acd6520 Mon Sep 17 00:00:00 2001 From: Nathan Zylbersztejn Date: Fri, 17 Apr 2020 14:01:33 -0400 Subject: [PATCH 01/10] docs: webhooks wip --- guide/deployment/webhooks.mdx | 88 +++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 guide/deployment/webhooks.mdx diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx new file mode 100644 index 0000000..689a157 --- /dev/null +++ b/guide/deployment/webhooks.mdx @@ -0,0 +1,88 @@ +--- +name: Server installation +route: /docs/deployment/installation/ +menu: Deployment +meta: + - name: description + content: "Integrate Botfront with your environment" + - name: keywords + content: botfront webhooks +--- + +# webhooks + +To map Botfront features with the specificity of your infrastructure, you can implement webhooks that will be invoked by Botfront. + + +## Restart Rasa + +If set, this webhook will be invoked when a user edits `endpoints` or `credentials`, or performs any action requiring Rasa to restart. + +The payload sent to the webhook will have the following specification: + +#### Request + +If setThe payload sent to the webhook will have the following specification: + +```json +{ + "field": "example value" # Value can be x,y,z +} +``` + +#### Response + + +```json +{ + "field": "example value" # Any comment or explanation +} +``` + +### Upload image + +If set, an upload widget will be available in the dialog builder. The webhook will be invoked when a user uploads an image. + +#### Request + +If setThe payload sent to the webhook will have the following specification: + +```json +{ + "field": "example value" # Value can be x,y,z +} +``` + +#### Response + +The service must return a response with the following specification: + +```json +{ + "field": "example value" # Any comment or explanation +} +``` + +## Delete image + +If set, an upload widget will be available in the dialog builder. The webhook will be invoked when a user deletes an image. + +#### Request + +If setThe payload sent to the webhook will have the following specification: + +```json +{ + "field": "example value" # Value can be x,y,z +} +``` + +### Response + +The service must return a response with the following specification: + +```json +{ + "field": "example value" # Any comment or explanation +} +``` \ No newline at end of file From 4db6abef27bd3530f0574680f42d433a56349de7 Mon Sep 17 00:00:00 2001 From: Nathan Zylbersztejn Date: Fri, 17 Apr 2020 14:03:26 -0400 Subject: [PATCH 02/10] availability in webhooks --- guide/deployment/webhooks.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 689a157..0425211 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -9,6 +9,8 @@ meta: content: botfront webhooks --- +Available in: + # webhooks To map Botfront features with the specificity of your infrastructure, you can implement webhooks that will be invoked by Botfront. From 7fcfda90e3045599e8d73ad3e53d1bd9c64298b6 Mon Sep 17 00:00:00 2001 From: Guillaume TECHER Date: Fri, 17 Apr 2020 14:21:25 -0400 Subject: [PATCH 03/10] refactor: add documentation for the restart rasa webhook --- guide/deployment/webhooks.mdx | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 0425211..4e07bab 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -24,22 +24,17 @@ The payload sent to the webhook will have the following specification: #### Request -If setThe payload sent to the webhook will have the following specification: +If set, the payload sent to the webhook will have the following specification: ```json { - "field": "example value" # Value can be x,y,z + "projectId": "bf" # id of your project } ``` #### Response - -```json -{ - "field": "example value" # Any comment or explanation -} -``` +This route does not return a json. Botfront only expect the http status of the call to your restart rasa ### Upload image From 723ae136951c6601900b7c4007196583eb11a2d2 Mon Sep 17 00:00:00 2001 From: pheel Date: Tue, 28 Apr 2020 16:32:38 -0400 Subject: [PATCH 04/10] fix bad snippets --- guide/deployment/webhooks.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 4e07bab..8cd6a72 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -26,9 +26,9 @@ The payload sent to the webhook will have the following specification: If set, the payload sent to the webhook will have the following specification: -```json +```js { - "projectId": "bf" # id of your project + "projectId": "bf" // id of your project } ``` @@ -44,9 +44,9 @@ If set, an upload widget will be available in the dialog builder. The webhook wi If setThe payload sent to the webhook will have the following specification: -```json +```js { - "field": "example value" # Value can be x,y,z + "field": "example value" // value can be x,y,z } ``` @@ -54,9 +54,9 @@ If setThe payload sent to the webhook will have the following specification: The service must return a response with the following specification: -```json +```js { - "field": "example value" # Any comment or explanation + "field": "example value" // any comment or explanation } ``` @@ -68,9 +68,9 @@ If set, an upload widget will be available in the dialog builder. The webhook wi If setThe payload sent to the webhook will have the following specification: -```json +```js { - "field": "example value" # Value can be x,y,z + "field": "example value" // value can be x,y,z } ``` @@ -78,8 +78,8 @@ If setThe payload sent to the webhook will have the following specification: The service must return a response with the following specification: -```json +```js { - "field": "example value" # Any comment or explanation + "field": "example value" // any comment or explanation } -``` \ No newline at end of file +``` From 1baa80397dab2fbe5d5e5707d22fb2f20f3acea9 Mon Sep 17 00:00:00 2001 From: pheel Date: Tue, 28 Apr 2020 16:33:16 -0400 Subject: [PATCH 05/10] fix header --- guide/deployment/webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 8cd6a72..818b42e 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -36,7 +36,7 @@ If set, the payload sent to the webhook will have the following specification: This route does not return a json. Botfront only expect the http status of the call to your restart rasa -### Upload image +## Upload image If set, an upload widget will be available in the dialog builder. The webhook will be invoked when a user uploads an image. From 0005ab75ac53f9f2607636b713d982929b14f19a Mon Sep 17 00:00:00 2001 From: pheel Date: Tue, 28 Apr 2020 17:04:41 -0400 Subject: [PATCH 06/10] add specs for image upload/delete webhooks --- guide/deployment/webhooks.mdx | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 818b42e..8606d98 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -11,7 +11,7 @@ meta: Available in: -# webhooks +# Webhooks To map Botfront features with the specificity of your infrastructure, you can implement webhooks that will be invoked by Botfront. @@ -20,15 +20,11 @@ To map Botfront features with the specificity of your infrastructure, you can im If set, this webhook will be invoked when a user edits `endpoints` or `credentials`, or performs any action requiring Rasa to restart. -The payload sent to the webhook will have the following specification: - #### Request -If set, the payload sent to the webhook will have the following specification: - ```js { - "projectId": "bf" // id of your project + "projectId": string } ``` @@ -42,44 +38,37 @@ If set, an upload widget will be available in the dialog builder. The webhook wi #### Request -If setThe payload sent to the webhook will have the following specification: - ```js { - "field": "example value" // value can be x,y,z + "projectId": string, + "data": string, // image encoded in base64 + "mimeType": string, + "language": string, + "responseId": string // template name followed by unix timestamp, e.g. utter_get_started_1588107073256 } ``` #### Response -The service must return a response with the following specification: - ```js { - "field": "example value" // any comment or explanation + "uri": string // the publicly accessible URI for the asset just received } ``` ## Delete image -If set, an upload widget will be available in the dialog builder. The webhook will be invoked when a user deletes an image. +The webhook will be invoked by Botfront when an image URL is no longer used in a response. The request will be sent whether or not the resource actually exists on the server. #### Request -If setThe payload sent to the webhook will have the following specification: - ```js { - "field": "example value" // value can be x,y,z + "projectId": string, + "uri": string // the publicly accessible URI for the asset to be deleted } ``` ### Response -The service must return a response with the following specification: - -```js -{ - "field": "example value" // any comment or explanation -} -``` +Botfront expects a 204 success response, and a 404 if ressource was not found. Any other response may signal an error to the user in the future. From 8edd61bca589e1c01b76ec77682e0ab999110310 Mon Sep 17 00:00:00 2001 From: Guillaume TECHER Date: Fri, 1 May 2020 11:15:09 -0400 Subject: [PATCH 07/10] refactor: add deploy webhooks documentation --- guide/deployment/webhooks.mdx | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 8606d98..57fc1fe 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -72,3 +72,28 @@ The webhook will be invoked by Botfront when an image URL is no longer used in a ### Response Botfront expects a 204 success response, and a 404 if ressource was not found. Any other response may signal an error to the user in the future. + + + +## Deploy webhook + +If set, and you project has environements, the deploy menu will be available under nex to the training button + +#### Request + +Botfront will send a request to the api with the following informations + +```js +{ + "projectId" : string, + "namespace" : string, + "environment" : string, + "data" : string, // base64 conversion of the model archive + "mimeType" string, +} +``` + +#### Response + +Botfront except a 200 success response, other response are treated as errors. +You can and a message property in the error response body that will be displayed to the user. \ No newline at end of file From 8045a53dc60853aea946c8b66fba891ba65dc810 Mon Sep 17 00:00:00 2001 From: Guillaume TECHER Date: Thu, 7 May 2020 10:18:52 -0400 Subject: [PATCH 08/10] refactor: update restart rasa webhook --- guide/deployment/webhooks.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 57fc1fe..662a1ca 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -24,7 +24,8 @@ If set, this webhook will be invoked when a user edits `endpoints` or `credentia ```js { - "projectId": string + "projectId": string, + "environment" : string, } ``` @@ -77,7 +78,7 @@ Botfront expects a 204 success response, and a 404 if ressource was not found. A ## Deploy webhook -If set, and you project has environements, the deploy menu will be available under nex to the training button +If set, and you project has environements, the deploy menu will be available next to the training button #### Request From cc5ddcb7acdbb861271d3d33deaa7dd551372d8f Mon Sep 17 00:00:00 2001 From: pheel Date: Tue, 7 Jul 2020 16:11:03 -0400 Subject: [PATCH 09/10] add Report Crash to Webhook docs --- guide/deployment/webhooks.mdx | 38 +++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx index 662a1ca..758d1c2 100644 --- a/guide/deployment/webhooks.mdx +++ b/guide/deployment/webhooks.mdx @@ -33,7 +33,7 @@ If set, this webhook will be invoked when a user edits `endpoints` or `credentia This route does not return a json. Botfront only expect the http status of the call to your restart rasa -## Upload image +## Upload Image If set, an upload widget will be available in the dialog builder. The webhook will be invoked when a user uploads an image. @@ -57,7 +57,7 @@ If set, an upload widget will be available in the dialog builder. The webhook wi } ``` -## Delete image +## Delete Image The webhook will be invoked by Botfront when an image URL is no longer used in a response. The request will be sent whether or not the resource actually exists on the server. @@ -70,19 +70,18 @@ The webhook will be invoked by Botfront when an image URL is no longer used in a } ``` -### Response +#### Response Botfront expects a 204 success response, and a 404 if ressource was not found. Any other response may signal an error to the user in the future. +## Deploy -## Deploy webhook - -If set, and you project has environements, the deploy menu will be available next to the training button +If set, and your project has environements, the deploy menu will be available next to the training button. #### Request -Botfront will send a request to the api with the following informations +Botfront will send a request to the api with the following information ```js { @@ -97,4 +96,27 @@ Botfront will send a request to the api with the following informations #### Response Botfront except a 200 success response, other response are treated as errors. -You can and a message property in the error response body that will be displayed to the user. \ No newline at end of file +You can and a message property in the error response body that will be displayed to the user. + + + +## Report Crash + +If set, browser crashes caused by Botfront will be reported to the webhook automatically. + +#### Request + +Botfront will forward the following to the webhook: + +```js +{ + "version": string, + "path": string, + "error": string, + "trace": string +} +``` + +#### Response + +Success-like responses (e.g. 200) are treated as successful. From 053b8782f4eed650883e879b9906842fe3d3c500 Mon Sep 17 00:00:00 2001 From: Nathan Zylbersztejn Date: Mon, 10 Aug 2020 15:06:36 -0400 Subject: [PATCH 10/10] webhooks --- guide/deployment/webhooks.mdx | 131 ++++++++++++++++++++++++++++++++++ menu.json | 1 + 2 files changed, 132 insertions(+) create mode 100644 guide/deployment/webhooks.mdx diff --git a/guide/deployment/webhooks.mdx b/guide/deployment/webhooks.mdx new file mode 100644 index 0000000..ee47322 --- /dev/null +++ b/guide/deployment/webhooks.mdx @@ -0,0 +1,131 @@ +--- +name: Integration +route: /docs/installation/integration/ +menu: Installation +meta: + - name: description + content: "Integrate Botfront with your environment" + - name: keywords + content: botfront webhooks +--- + +Available in: + +# Webhooks + +Some Botfront features implies being able to communicate with the underlying IT infrastructure. +Since every infrastructure is specific, some feature may require custom implementation to be available in Botfront. +For example, restarting a Rasa instance, uploading medias, or deploying are very specific on how your IT infrastructure is organized. + +Webhooks allow a deeper integration in your IT environment. + +You can define webhooks at the platform lever in **Admin -> Settings -> Webhooks**. + +## Available webhooks + +### Restart Rasa + +If set, this webhook will be invoked when changing `endpoints`, `credentials`, or performing any action requiring Rasa to restart. + +#### Expected request body + +```js +{ + "projectId": string, + "environment" : string, +} +``` + +#### Expected response + +This route does not return a an object. Botfront only expects the http status code. + +### Upload Image + +Implementing this webhook enables image upload in Botfront. + +#### Expected request body + +```js +{ + "projectId": string, + "data": string, // image encoded in base64 + "mimeType": string, + "language": string, + "responseId": string // template name followed by unix timestamp, e.g. utter_get_started_1588107073256 +} +``` + +#### Expected response + +```js +{ + "uri": string // the publicly accessible URI for the asset just received +} +``` + +### Delete Image + +The webhook will be invoked by Botfront when an image URL is no longer used in a response. The request will be sent whether or not the resource actually exists on the server. + +#### Expected request body + +```js +{ + "projectId": string, + "uri": string // the publicly accessible URI for the asset to be deleted +} +``` + +#### Expected response + +Botfront expects a 204 success response, and a 404 if ressource was not found. Any other response may signal an error to the user in the future. + + +### Deploy + +If set, and if your project has environments defined, the deploy menu will be available next to the training button. +When training, the webhook will be invoked with the `development` environment. +When deploying, the webhook will be invoked with the `production` environment. + +#### Request + +Botfront will send a request to the api with the following parameters. + +```js +{ + "projectId" : string, + "namespace" : string, + "environment" : string, // "development" or "production" + "data" : string, // base64 conversion of the model archive + "mimeType" string, +} +``` + +#### Expected response + +Botfront except a 200 success response, other response are treated as errors. +You can and a message property in the error response body that will be displayed to the user. + + + +### Report Crash + +If set, browser crashes traces will sent to this webhook. + +#### Request + +Botfront will forward the following to the webhook: + +```js +{ + "version": string, + "path": string, + "error": string, + "trace": string +} +``` + +#### Expected response + +Success-like responses (e.g. 200) are treated as successful. diff --git a/menu.json b/menu.json index 7e1b695..6defd85 100644 --- a/menu.json +++ b/menu.json @@ -42,6 +42,7 @@ "menu": [ "On your local machine", "On servers or clusters", + "Integration", "Using the CLI", "Migration guide" ]