Receive Webhooks

As mentioned before, you can view user submissions in the dashboard and using the API. The third and last way are webhooks. Find out everything you need to know here!

What are webhooks?

Webhooks work like notifications. You can set up a target webhook URL for a popup in the EasePop editor. Whenever a user performs a submission using this popup, you will then be notified on the target URL from us with a HTTP POST request containing the submission payload. This means you don't have to query the API repeatedly to get new submissions but can be notified by us instead.

Setting up webhook delivery

To enable webhook delivery for a specific popup, go into the EasePop editor and select the "Elements" tab in the sidebar. Scroll down to Form Submission and enter the URL where you want webhooks to be delivered.

Make sure the URL you enter is publicly accessible. Private IP addresses, localhost, or other inaccessible URLs are not accepted.

Receive Webhooks

To receive webhooks, set up a web server listening on the target URL you set in the EasePop editor. Your server should accept HTTP POST requests with Content-Type: application/json.

Verify authenticity

Before processing an incoming request, it is important to verify the integrity of the payload. As your webhook endpoint has to be publicly accessible for EasePop to successfully deliver submissions, you need to verify the request actually originates from EasePop. For this reason, we provide an HMAC-SHA256 digest of the request body, signed with a private webhook secret.

Calculate the signature yourself using a method like this and then verify the signature provided in the X-Webhook-Signature header.

import crypto from 'crypto';

function calculateHash(payload: unknown, secret: string) {
  const payloadString = JSON.stringify(payload);
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payloadString);
  return `sha256=${hmac.digest('hex')}`;
}

// Function handling your request, pseudocode
function onRequest(request: { headers: Record<string, string>; body: unknown }) {
  const receivedSignature = request.headers["x-webhook-signature"];
  const referenceHash = calculateHash(request.body, process.env.EASEPOP_WEBHOOK_SECRET);

  if (receivedSignature !== referenceHash) {
    return; // Stop further processing
  }

  // Continue with processing
  const popupId = request.body.popupId;
}

You can retrieve your webhook secret from the domain page in your dashboard. Click "Manage" on your domain, scroll until "Webhook Secret" and copy it.

Acknowledge receipt

If you have successfully processed the webhook, respond with any 2xx HTTP response code. If you respond with a non‑2xx response code, or don't respond in 15 seconds, the request will be marked as failed in our system and retried. We support an exponential backoff retry strategy which means the same request will be repeated up to 5 times if you don't acknowledge it.

For this reason, we add an id field into the body of the request. This is unique for each submission, so you can verify whether you have already processed a webhook or not.

Sample JSON Body Payload

{
  "id": "90912701-9c3c-4225-8553-1e19633696c8",
  "popupId": "b5e2ef8c-93a1-49a4-88c9-94b9e3719775",
  "formData": {
    "email": "user@mail.com"
  },
  "timestamp": "2025-10-01T21:28:04.315Z",
  "domain": "example.com"
}