What is Webhook?

Webhooks operate on the concept of “event reaction” (we need not call, but it will call when an event happens), and thus avoids the need for constant polling of the server-side application by the client-side application. Therefore, rather than the client-side application constantly polling the server-side application to check for new events, the server-side application calls the client-side application (by invoking a client provided webhook URL) anytime the server-side has something new to report to the client. This is the core concept of the webhook.

Thus, with webhooks, you can get push notifications when certain events happen on the server. You do not need to poll the API anymore to observe if these events have occurred. You can just ‘subscribe’ to an event with webhooks.

Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity. Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a customer has taken a particular action, such as initiating or replying to a conversation.

Creating and Managing Webhooks

You can create and manage the webhooks with the REST API available here. 

Trusted source validation (via signature)

What is a public key and how to generate it via API?

SalesIQ signs every webhook event passed on to the endpoint URL using RSA Cryptosystem.

• We use SHA256 with RSA as the signature algorithm.
• The signature is Base64 encoded
• The charset used is UTF-8

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.

To generate the public key use the following API:

API: /api/v2/{screenname}/webhooks/{id}/keys
METHOD : POST
Scope: SalesIQ.webhooks.CREATE

To delete the public key use the following API:

API: /api/v2/{screenname}/webhooks/{id}/keys/{keyid}
METHOD : DELETE
Scope: SalesIQ.webhooks.DELETE 

The trusted source validation is to secure the Webhooks, i.e., for you (integration services) to verify the data sent is from SalesIQ services by getting the public key in the API response and validating the signature available in the x-siqsignature request headers for that data. If the signature is valid, then the source can be trusted. This process is to secure the Webhooks from unauthorized access.

To validate the source with the help of signature header:

HEADERS : 
{
x-siqsignature : $signature 
}

If you wish to set up a secure callback, then create the webhook and set the secure as true ("secured:true".)

Payload: 

{
webhook : {
url : $webhookurl,
secured : <boolean>}, 
published : <boolean>