Leverage API hooks

Note: 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.

When emails 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 /api1/hooks endpoint.

Advantages of the hooks

When your goal is to receive the new emails 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 emails,
• You will receive them much faster, we will take care of posting the collected emails 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 page:

Creating a hook

Let's say we want to receive the emails associated with our "Welcome UK" pop-up. Once we have generated an API key, we can configure a hook to post emails to https://yourwebsite.com/hook:

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

Managing your hooks through the WisePops API

You might want to manage your hooks through our API if you want to automate hooks creation and deletion.

Creating a hook

Create a hook by issuing a POST request to the /api1/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. We currently support only one event: email .
• target_url (required) - The URL that will receive collected emails.
• wisepop_id - If you want the hook to transmit emails only from a specific pop-up.

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

curl -H 'Authorization: WISEPOPS-API key="YOUR_API_KEY_HERE"' -H 'Content-Type: application/json' -d '{"event":"email","target_url":"https://yourwebsite.com/hook"}' 'https://app.wisepops.com/api1/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/api1/hooks?hook_id=42'

The Payload

The posted payload is similar to the response body of the /api1/emails endpoint. Keep in mind that multiple emails can be sent in the same payload.

[
  {
    "created_at": "2017-03-01 01:12:41",
    "email": "example@example.com",
    "wisepop_id": 12345,
    "wisepop_name": "Live Wisepop",
    "ip": "127.0.0.1",
    "country_code": "US",
    "other_fields": {
      "Gender": "male",
      "City": "New York"
    }
  },
  {
    "created_at": "2017-03-01 03:56:00",
    "email": "other.example@example.com",
    "wisepop_id": 12345,
    "wisepop_name": "Live Wisepop",
    "ip": "127.0.0.1",
    "country_code": "US",
    "other_fields": {
      "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. You should not rely on the IP.

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']) || $_SERVER['HTTP_X_WISEPOPS_SIGNATURE'] !== $signature) {
    throw new Exception('Signature verification failed');
}

$emails = json_decode($payload);