Get each result on your own URL.

What it is for

MailCheckUP calls the customer. They do not poll. Use a webhook when a system should react as soon as addresses finish: drop deliverable rows into a sheet, remove undeliverable rows from a sender, or mark a list done. Use the portal or list_results when a person just wants to read the file. A webhook does not find emails, does not send the customer's campaign, and does not mean a deliverable address will reach the inbox.

Who can set one up

• Workspace owner or admin, on the Webhook page after login.
• Members cannot add or edit endpoints.
• An API key cannot create one.
• MCP list_webhooks returns the URL, enabled flag, event names, retry count, and gap. It does not return the secret.

Open the Webhook page

How to connect

1. Open https://cp.mailcheckup.net/webhooks.
2. Add an HTTPS URL. Production rejects plain HTTP.
3. Pick the events. If the customer sends none, the default subscription is list.completed only.
4. Optionally set retries. Default is 6 tries, 60 seconds apart.
5. Copy the workspace signing secret from that page. It starts with whsec_. There is one secret for the workspace. Every endpoint is signed with it. Owners and admins can see it on the Webhook page. Do not put a real secret in docs, screenshots, or a chat prompt. Use the placeholder whsec_your_secret in snippets only.
6. Send a test from the same page. The test body has "test": true. A test is not retried.

More than one URL is allowed. Each URL has its own event list, try count, and gap. Disabling an endpoint stops delivery to that URL. It does not rotate the secret.

The HTTP call

The signature is HMAC-SHA256 of the exact raw body, keyed with the workspace secret. Compare the header to sha256= plus the hex digest, in constant time.

Check the signature

rawBody is the request body before JSON parsing. In Node that is the raw Buffer. In Python it is the raw bytes, not request.json(). Return 2xx after the event id is stored. Do the slow work after the response. If the handler crosses 8 seconds, MailCheckUP treats the call as a timeout and tries again. The samples use the placeholder whsec_your_secret. They do not contain a live secret.

import { createHmac, timingSafeEqual } from "node:crypto";
function verifyMailCheckupWebhook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

import hmac, hashlib
def verify_mailcheckup_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    expected = "sha256=" + digest
    return hmac.compare_digest(expected, signature_header)

Envelope

Every event uses the same wrapper. id starts with evt_ and stays the same on every retry. Store it and ignore a repeat. x-mailcheckup-delivery is the attempt id and changes each try.

{"id":"evt_…","type":"list.completed","created_at":"2026-09-28T12:00:00.000Z","data":{}}

A test adds "test": true inside data, plus obvious sample values (Test list, person@example.com). Do not import test rows into a live audience.

Ten events only

Unknown names are rejected. Subscribe only to what the receiver will act on.

List events

Email events

Each POST carries up to 50 new addresses. If more are waiting, the next batch follows on the next pass, about 20 seconds later. An address already sent on that endpoint is not sent again. These events only include checks that finished after the endpoint was created. Turning on email.valid does not replay old lists.

data.emails[] carries email, code, list_id, and list_name.

Retries

Tries 1 to 10, default 6. Gap 10 to 86400 seconds, default 60. Tries means the total number of calls if the URL does not return 2xx. The gap stays fixed. It does not grow. The JSON id is unchanged across tries. The delivery header changes.

Not retried: localhost, .local, .internal, a private or link-local address, or a URL that is not http(s). A URL with a username or password is rejected. DNS that points at a private address is not called.

After three failed deliveries in a row, MailCheckUP emails the workspace owners and admins once, then stays quiet for 24 hours. The endpoint is not deleted. Fix the URL or the handler, then use the test button.

The delivery log keeps 30 days. Status filters: success, failed, pending, waiting, sending. The log stores up to 2000 characters of the response. Owners and admins can clear that log. Clearing it does not resend the events.

Questions