Webhooks

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)
• Panel member has been added (EventType=PanelMemberAdded)
• Panel member has been removed (EventType=PanelMemberRemoved)
• Panel member has been updated (EventType=PanelMemberUpdated)
• Survey has been closed (EventType=SurveyClosed)

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:

• CreateWebHook
• UpdateWebHook
• 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: Public API – CH Datacenter
EU Datacenter: Public API – EU Datacenter

What happens if the notified system is not available?

In case that the WebHook call is not successful the call will be retried with an exponential backup starting from 5 minutes.

After 5 non-successful retries the notification is no longer delivered.

Common Scenarios

POST /publicapi/Panel/v3/CreateWebHook
Content-Type: application/json

Get notifications for completed interview of specific survey

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

Get notifications for completed interview of all surveys

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

Get notifications for all hard bounces

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

Get notifications for all closed surveys

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

What data returns the Webhooks?

Webhooks return the entity for which the notification was generated. This could be:

• Interview
• Panel Member
• Bounce
• Opt-Out
• Survey

The information provided in the Webhook shall be sufficient to avoid another reading roundtrip.