Leverage Web Hooks

Lisa Fockens Updated by Lisa Fockens

When sign-up forms and surveys are collected, we can send an HTTP POST payload to a hook's URL. You can manage your hooks through the Wisepops interface, or by using the /api2/hooks endpoint.

The API key and hooks are associated with a specific website. If you have multiple websites configured in Wisepops, you'll need to use the correct key and create distinct hooks for each of these websites.

Advantages of the hooks

When your goal is to receive the new forms Wisepops collects, we strongly suggest you to use the hooks here instead of periodically calling our API:

  • You won't have to play with the collected_after parameter. By design, you will only receive newly collected forms,
  • You will receive them much faster, we will take care of posting the collected forms to the target as soon as our system has them ready,
  • Hooks are not API rate limited.

Managing your hooks through the Wisepops interface

You can manage your hooks from the Email API settings.

Creating a hook

Let's say we want to receive the emails associated with our "Welcome UK" popup. We can configure a hook to post the emails to https://example.com/hook:

Here, we assume that we own the domain example.com, and that /hook is a URL ready to receive the Wisepops payload. You can find an example of script receiving such payload at the end of this page.

The event (Email, Phone or Survey) let you choose which type of forms you want to receive. It's related to the type of block the campaign contains: a sign-up block, phone block or survey block.


Managing your hooks through the Wisepops API

As a technical partner, you may want to manage hooks through our API. This way, hooks creation and deletion can be automated across multiple Wisepops accounts. This is rarely useful for Wisepops customers, as managing hooks through our interface is easier.

Creating a hook

Create a hook by issuing a POST request to the /api2/hooks endpoint. Parameters should be JSON encoded, and you must add the header Content-Type: application/json.

The parameters are:

  • event (required) - The event that triggers your hook. Allowed values are email, phone and survey. Respectively for sign-up blocks, phone blocks and survey blocks.
  • target_url (required) - The URL that will receive collected forms.
  • wisepop_id - If you want the hook to transmit forms only from a specific pop-up.

The following request will create a new hook that will transmit all collected emails to https://example.com/hook:

curl -H 'Authorization: WISEPOPS-API key="YOUR_API_KEY_HERE"' -H 'Content-Type: application/json' -d '{"event":"email","target_url":"https://example.com/hook"}' 'https://app.wisepops.com/api2/hooks'

The response will contain the ID of the created hook:

{
  "id": 42
}

Deleting a hook

To delete a hook, perform a DELETE request.

There is only one required parameter: hook_id. It is the ID received when creating the hook.

This is the request to delete the hook #42:

curl -H 'Authorization: WISEPOPS-API key="YOUR_API_KEY_HERE"'
-XDELETE 'https://app.wisepops.com/api2/hooks?hook_id=42'

The Payload

The body of the request sent by Wisepops gives details of the collected lead.

  • The fields key contains the data collected through your form's fields,
  • The form_session key allows you to merge incremental submits of the same form in a multi-step campaign,
  • Keep in mind that multiple leads can be sent within a single payload.

[
{
"collected_at": "2019-10-10T10:10:58.389Z",
"wisepop_id": 12345,
"form_session": "e3ff440d-602f-414a-85fa-9d6268d0a82a",
"ip": "127.0.0.1",
"country_code": "US",
"fields": {
"email": "example@example.com",
"Gender": "male",
"City": "New York"
}
},
{
"collected_at": "2019-10-10T10:10:59.010Z",
"wisepop_id": 12345,
"form_session": "549f53dc-c691-488c-9bb2-9c0ef8460d23",
"ip": "127.0.0.1",
"country_code": "US",
"fields": {
"email": "other.example@example.com",
"Gender": "female",
"City": "Seattle"
}
}
]


Additionally, the HTTP header X-Wisepops-Signature will be set. It will contain the HMAC hex digest of the payload, using your API key as a cryptographic key. This lets you verify that Wisepops is the emitter of the query.

This is an example of a PHP script, behind Apache or Nginx, that receives a payload:

<?php
$apiKey = 'YOUR_API_KEY_HERE';
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $apiKey);

if (!isset($_SERVER, $_SERVER['HTTP_X_WISEPOPS_SIGNATURE']) ||
!hash_equals($signature, $_SERVER['HTTP_X_WISEPOPS_SIGNATURE']) {
    throw new Exception('Signature verification failed');
}

$contacts = json_decode($payload);

foreach ($contacts as $contact) {
// Upsert on $contact->form_session
}


Our requests' origin IP is 34.68.181.17, you can whitelist it if you need to configure a firewall. You can subscribe to this list to get notified if we need to add new IPs. 

Wisepops API basics

Contact