Webhooks are a powerful feature that allow you to flexibly process the data collected by Wisepops in real-time. When sign-up forms and surveys are collected, we send an HTTP POST payload to a hook's URL in a matter of seconds.
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 instead of periodically calling our API:
Real-time delivery
Forms are posted to your target URL in a matter of seconds.
Built-in reliability
Our system automatically retries failed requests and alerts you via email or dashboard if issues persist.
Simpler integration
No need to schedule periodic API calls or manage thecollected_afterparameter.
No API rate limits
Webhooks scale effortlessly without hitting request caps.
You can manage your hooks through the Wisepops interface, or by using the /api2/hooks endpoint. Either way, once a hook is created, the data flows from Wisepops to your target URL every time data is collected in your Wisepops campaigns.
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 offer - new visitors" 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 a script receiving this payload at the end of this page.
The event (Email, Phone, or Survey) lets you choose which type of form data you want to receive. This corresponds to the type of block the campaign contains: a sign-up block, phone block, or survey block.
Testing your hook
With our interface, you can easily check if your target URL is working as expected. In the Settings > Email API page, click the "Test hook" icon of the hook you want to test.
It opens a modal allowing you to send a test payload to the configured target URL, and inspect the response received by Wisepops.
Managing your hooks through the Wisepops API
As a technical partner, you may want to manage hooks through our API. This allows hook creation and deletion to be automated across multiple Wisepops accounts. While useful for technical partners, most customers find managing hooks through our interface to be easier and more convenient.
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 areemail,phoneandsurvey. These correspond to sign-up blocks, phone blocks, and survey blocks, respectively.target_url(required) - The URL that will receive collected forms.wisepop_id- If you want the hook to transmit forms only from a specific popup. This is the ID of a Popups campaign, visible in the /api2/wisepops endpoint, or in the Popups builder URL. Leave this empty to sync leads of all campaigns.
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 provides details of the collected lead.
The
fieldskey contains the data collected through your form's fields.The
form_sessionkey allows you to merge incremental submissions 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 request.
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 allowlist it if you need to configure a firewall. You can subscribe to this list to be notified if we need to add new IPs.