Skip to content

// e-commerce and billing

Via API

Paddle email verification with pingutil

As merchant of record, Paddle emails receipts and invoices to whatever address the buyer typed, and a typo or throwaway inbox means the customer never sees them. Handling the customer.created webhook, verifying the address with pingutil and saving the result in the customer custom_data gives your app a signal for trials, license delivery and support.

Where it connects: Paddle Billing webhooks (customer.created, transaction.completed) plus customer custom_data via the Customers API

What goes wrong without it

  • Buyers mistype their email in the Paddle checkout and then email support asking where their license key went.
  • Trial abusers create a new Paddle customer with a temp-mail address for every trial.
  • We cannot tell which refund requests come from real customers and which from throwaway accounts.

What you can do with Paddle and pingutil

  • Save the result on the Paddle customer

    Write the pingutil status and reason to customer custom_data so it travels with the customer in later webhooks and API responses.

  • Gate trials on a real address

    When category is disposable or verdict.is_spam is true, your app can decline a second trial or ask for another address.

  • Recover lost license emails

    If did_you_mean is set after transaction.completed, show the suggestion in your app so the buyer can correct the address and get their receipt.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and a Paddle API key with permission to update customers.

  2. 2

    Create a notification destination in Paddle for customer.created (and transaction.completed if you need it), and copy its secret key.

  3. 3

    Verify each request with paddle.webhooks.unmarshal using the raw body and the Paddle-Signature header.

  4. 4

    Respond 200 within five seconds, then call pingutil in the background.

  5. 5

    Write the result with paddle.customers.update and customData.

Webhook handler for customer.created (Paddle Node SDK)
import express from 'express';
import { Paddle, EventName } from '@paddle/paddle-node-sdk';

const paddle = new Paddle(process.env.PADDLE_API_KEY);
const app = express();

app.post('/webhooks/paddle', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await paddle.webhooks.unmarshal(req.body.toString(), process.env.PADDLE_WEBHOOK_SECRET, req.get('paddle-signature'));
  } catch {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // Paddle waits five seconds

  if (event.eventType === EventName.CustomerCreated) {
    tagCustomer(event.data.id, event.data.email).catch(console.error);
  }
});

async function tagCustomer(customerId, email) {
  let result;
  try {
    const res = await fetch('https://pingutil.com/v1/verify', {
      method: 'POST',
      headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(30000),
    });
    if (!res.ok) return; // fail open
    result = await res.json();
  } catch {
    return;
  }

  await paddle.customers.update(customerId, {
    customData: {
      pingutil_status: result.status,
      pingutil_reason: result.reason,
      pingutil_disposable: result.checks.disposable,
    },
  });
}

app.listen(3000);

What to do with each result

pingutil resultAction in Paddle
status: "invalid"Show an in-app banner asking the buyer to fix their email so Paddle receipts and invoices reach them.
did_you_mean is setOffer the suggested address in your account settings page.
checks.disposable: trueDecline a repeat trial or require a verified address before activating it.
status: "risky" or "unknown"Store in custom_data only.

Limits to plan for

  • Paddle expects a 200 within five seconds and retries on failure, and a mailbox check can take longer, so verify after responding.
  • If you already keep your own keys in custom_data, include them in the update payload so the pingutil fields sit next to them.
  • Webhooks fire after the customer exists. To check before checkout, collect the email in your own form and verify it from your backend first.

Paddle documentation

Paddle is a trademark of its owner. This integration uses Paddle's documented extension points; it is not an official Paddle app.

Common questions

Does this work with Paddle Classic?
The snippet targets Paddle Billing, which has customer.created and the Node SDK unmarshal helper. Paddle Classic uses a different webhook format.
Can I block the purchase?
Not from a webhook. We recommend letting the payment go through and fixing the address afterwards, since the buyer has already paid.

Stop bad addresses in Paddle today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Paddle setup will receive.