1. Home
  2. Application Programming Interface
  3. Webhooks – How to use them

Webhooks – How to use them

What are Webhooks?

Webhooks are user defined HTTPS callbacks, which could be subscribed to get notified for several survalyzer events. It allows to implement realtime integrations since the webhooks are triggered, when the event appears and make any polling for data obsolete.

What Webhooks does Survalyzer offer?

Survalyzer offers the folloing webhooks:

  • Survey approval request (EventType=ApprovalRequest)
  • Survey approved (EventType=Approved)
  • Interview has been completed (EventType=InterviewComplete)
  • Hard Bounce was received (EventType=HardBounce)
  • Opt-Out has been added (EventType=OptOutAdded)
  • Opt-Out has been removed (EventType=OptOutRemoved)

Which authentication mechanisms are supported for webhooks?

Survalyzer supports four different authentication strategies which offer a high grade of security.

Security by obscurity

This means that the URL which shall be called is not guessable. This is one of the oldest principles and widely used for example by Zapier. Links typically look like this:

https://domain.com/myservice/b1770d6f-b834-4796-a50c-8a040550935a

The last part of the url acts as a 32 character password and makes the link ungessable and therefore secure. The field SecurityToken remains empty.

Basic Authentication

This means Username and Password are base64 encoded transmitted by the Authorization header. The header for the credentials testuser and testpassword looks like this:

Authorization: Basic dGVzdHVzZXI6dGVzdHBhc3N3b3Jk

The value of the header including “Basic” should be transmitted in SecurityToken.

Bearer Authentication

This authentication scheme is similar to the basic authentication scheme but contains instead a base64 encoded username and password a signed JSON Web Token (JWT). The web token needs to be either static or have a reasonable exiration period. For example like a SSL-Certificate with one year. After that year the subscription needs to be recreated to exchange the static token. The Authorization header looks like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The value of the header including “Bearer” should be transmitted in SecurityToken.

Security Key Authentication

This authentication mechanism is simple and effective. The URL already contains the authentication keys. With this authentication scheme no aditional security token is required. The url looks like this:

https://mydomain.com/myservice?sv=2020-08-04&se=2121-10-01T00%3A00%3A00Z&sr=b&sp=r&sig=aDgbw2GIETt9587n3fHBA%2FEIphVYqBgRd3A2T0VspPU%3D

The service could validate the caller by the given signature. Since it is server to server communication transmitting the authentication in the URL is no security flaw.

Which Webhook APIs does Survalyzer offer?

Survalyzer offers three APIs to maintain Webhooks:

  • /publicapi/Webhook/v2/CreateWebHook
  • /publicapi/Webhook/v2/UpdateWebHook
  • /publicapi/Webhook/v2/DeleteWebHook

The CreateWebHook API registers an event subscription and returns a GUID to identify the registration. The UpdateWebHook and DeleteWebHook use this GUID to either update or delete the registration.

The full doumentation and a possibility to try it out can be found here:

Swiss Datacenter: https://api.survalyzer-swiss.app/
EU Datacenter: https://api.survalyzer-eu.app/

The section WebHooks is located at the bottom of the page. The management APIs are all secured with the Survalyzer Token which can be obtained by calling /publicapi/Authentication/v1/GetApiToken.

Common Scenarios

Get completed interview notifications for survey 123

/publicapi/Webhook/v2/CreateWebHook

Body:
{
  "eventType": "InterviewComplete",
  "entityIdentifier": "123", //SurveyId
  "webHookUrl": "https://domain.com/myservice/b1770d6f-b834-4796-a50c-8a040550935a"
}

Get completed interview notifications for all surveys

/publicapi/Webhook/v2/CreateWebHook

Body:
{
  "eventType": "InterviewComplete",
  "entityIdentifier": "*", //All SurveyIds
  "webHookUrl": "https://domain.com/myservice/b1770d6f-b834-4796-a50c-8a040550935a"
}

Get notifications about hard bounces

/publicapi/Webhook/v2/CreateWebHook

Body:
{
  "eventType": "HardBounce",
  "entityIdentifier": "*", //All SurveyIds
  "webHookUrl": "https://domain.com/myservice/b1770d6f-b834-4796-a50c-8a040550935a"
}

What data returns the Webhooks?

Each Webhook returns the related entity. The following example shows the notification response for the InterviewComplete event:

Webhook return interface definition in Swagger format.

The full documentation of all entities will be available soon in the following formats:

  • .NET Interface assembly (NuGet)
  • Swagger API Documentation

Updated on November 10, 2021

Was this article helpful?

Related Articles