Webhook Platform
- How to create a plug?
- How to configure the output for webhook?
- How to Edit/Delete the Plug?
- How to add Plugs to the Codeless bot builder?
- Webhook failure alert
How to create plugs using the Webhook platform?
Webhooks are an easy way to implement event reactions. Webhooks provide a mechanism whereby a server-side application can notify a client-side application when a new event (that the client-side application might be interested in) has occurred on the server. When you have actions in an external service, you can hook them up using webhooks.
Set up a profile:
- In the SalesIQ dashboard, navigate to Settings > Developers > Plugs.
- Inside the Plugs dashboard, click Add.
- Give your Plug a name, add a description, and choose the platform as Webhooks.
- Finally, click on Create Plug. You will be redirected to the selected plug builder.
Define parameters:
- The first step in creating plugs is defining the input and output parameters and their data types.
- Provide a name and select their datatypes. To add more parameters, click on Add.
Note: The input parameters will be sent as a map value with the "session" key in the payload. So, the input values can be fetched from the map (payload). And the corresponding output from the server (your server where the URL hits) will be displayed in the output response of the plug.
- The input parameters are from the codeless bot builder to do an action/function. Once the action is completed, the values are to be sent to the codeless bot as an output parameter. For example, to schedule a booking, we need the visitor's name, email, phone, date & time (input parameters). After the booking is completed, we can send the booking ID (output parameter) as a reference to the visitor.
- Then, click on Save.
Note: Learn how to configure output for webhook
Webhook registration:
- Provide the URL to invoke to create a connection.
Webhook Pre-requisites
- The "https" URL is recommended for security reasons.
- Our server can not connect with the URL with the port number.
- Ensure the URL can be accessed in public API clients such as Postman and Talend API Tester to be accessible in our server.
- Once the URL is provided, it will be pinged to get validated with the read time out of 5 seconds.
- If it is not reached within 5 seconds, an HTTP HEAD request gets triggered to the URL to check the status code 200.
- Ensure the webhook returns the response within 10 seconds. If not, the bot will not work.
- Furthermore, generate a public key to secure your webhook.
- Enable Secure your webhook to verify the data with a key pair validation. If this option is enabled, SalesIQ will create a signature for the payload data with the private key while executing the Webhook. The signature will be sent to the webhook server with the header "x-siqsignature".
- The Webhook server should get the signature from the 'x-siqsignature' header and verify it with the payload data received on their end and the public key using the same RSA Cryptosystem. If the verification fails, they can ensure that the data has been tampered or not sent from SalesIQ.
- SalesIQ signs every webhook event passed on to the endpoint URL using RSA Cryptosystem. The generated Public key can be copied and saved in the endpoint server, which can later be used to check the authenticity of the data received with the signature attached. We will generate a public and a private key pair.
- Public Key: The public key is displayed, whereas the private key is hidden. The webhook server will store the public key. The public and private keys are used for security and verification purposes. This process ensures two-layer security, they are:
- To ensure that the data is sent from the SalesIQ Server
- The data sent has not been tampered.
- A maximum of two public keys are allowed for a Webhook. If only one public key is available, the delete option will not appear. The Oldest key will be used during execution, and the key used will be indicated by the [In use] label.
Test and Publish:
- Click on Test to preview the Plug, and finally, click on Publish.
- Only published plugs will be listed in the codeless bot builder.
- Once the plug is executed, the desired output will be displayed as a response. This will be sent to the codeless bot builder.
How to configure the output for webhook?
You need to define the same name that you define for the output inside outputParameterName. The following is the list of return datatypes that are acceptable for outputdata:
Datatypes | Value |
date | "2020-12-31" |
number | 29 |
datetime | { "date_time":"2020-12-31T18:45", "time_zone_id":"Asia/Calcutta" } |
string | "Hello There!" |
phone | "08883169888" |
location | { "country":"USA", "country_code":"us", "city":"Seattle", "latitude":"8.77486", "district":"East District", "state":"Washington", "full_address":"9241 13th Ave SW Seattle, Washington(WA), 98106","postal_code":"628001","longitude":"78.13423" } |
"danny@zylker.com" | |
daterange | { "from":"2021-04-07", "to":"2021-04-19" } |
url | "https://zylker.com" |
IP | "123.23.32.12" |
numberlist | [ "123", "123.123", "123456789000" ] |
stringlist | [ "123", "Hello there!", "How are you?" ] |
timezone | "Asia/Calcutta" |
Syntax to configure output for webhook
{ "outputParameterName1": "outputData1", "outputParameterName2": "outputData2" }
How to Edit/Delete the Plug?
Edit the Plug:
- To edit the plug, navigate to Settings > Developers > Plugs. All your existing plugs will be listed here.
- Click on the plug you would like to edit.
- Then, click Configure profile to edit the plugs' name and description.
- To edit the plugs' code/script, Edit code, and you will be directed to the scripts platform.
Delete/Disable the Plug:
- To delete the plug, navigate to Settings > Developers > Plugs. All your existing widgets will be listed here.
- Hover over the plug to delete the plug, and the delete icon will appear.
- Toggle on the widget at the right to disable it.
How to add Plugs to the Codeless bot builder?
- In your Codeless bot builder, select the Plug block under Action Cards.
- Then, select the plug you want to add to the bot's flow.
- Next, provide the input parameters (Default value/bot context) for plug execution.
Note: Only published plugs are listed here.
- A static value can also be given as the plug input. Type the required value in the search box and click on the Set value.
- In the above reference, a static value "Website Bot" is declared for the Source plug.
- Next, provide a bot context to store the plug's output and use it in the next card to display it to the visitor.
- The above reference is a plug for scheduling appointments using Zoho booking. The "bookingid" is one of the plug's outputs, which returns the appointment's booking ID.
- It is stored in a bot context "visitor.booking.id" and used in an end card to display the booking ID to the visitor, as shown in the reference below.
Webhook failure alerts
When the webhook continuously fails under the below instances, SalesIQ will send an email alert to both the bot creator/modifier and the portal owner.
- No emails will be triggered for the first failure.
- The first warning email will be sent after the second failure, with no success within the past hour.
- The second warning/alert will be sent following the third failure, with no success within an hour of the first warning email.
- Upon the fourth failure, with no success within an hour since the second warning email, the bot will be disabled, and a third
- warning/alert email will be sent.
410 Error: If the webhook returns a 410 error at any time, it will be instantly deactivated, and a warning/alert email will be sent.