Setting up Webhooks for Real-time Verification

What Are Webhooks?

Webhooks are HTTP callbacks that Mailsfinder sends to your server whenever an event occurs, such as when an email verification completes or a bulk job finishes processing. Instead of polling the API repeatedly to check for results, webhooks push data to your application in real time, reducing latency and saving API credits. For the full list of available endpoints, see the API documentation.

Webhooks are available on all paid plans (Growth, Pro, and Enterprise). Free plan users can upgrade to access this feature.

Step 1: Configure Your Webhook Endpoint

Before registering a webhook with Mailsfinder, you need a publicly accessible HTTPS endpoint on your server that can receive POST requests. Here is a minimal example using Node.js and Express:

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhooks/mailsfinder', (req, res) => {
  // Verify the webhook signature
  const signature = req.headers['x-mailsfinder-signature'];
  const hash = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== hash) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook payload
  const { event, data } = req.body;
  console.log(`Received event: ${event}`, data);

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);

Step 2: Register the Webhook in Mailsfinder

Once your endpoint is ready, register it through the Mailsfinder dashboard or API:

1. Navigate to Settings > Webhooks in your Mailsfinder dashboard.
2. Click "Add Webhook" and enter your endpoint URL (e.g., https://yourapp.com/webhooks/mailsfinder).
3. Select the events you want to subscribe to: verification.completed, bulk_job.completed, bulk_job.failed.
4. Click "Save." Mailsfinder will send a test ping to verify your endpoint is reachable.

Alternatively, register via the API:

curl -X POST https://api.mailsfinder.com/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/mailsfinder",
    "events": ["verification.completed", "bulk_job.completed"],
    "secret": "your_webhook_secret"
  }'

Webhook Payload Format

Every webhook delivery includes a JSON body with the following structure:

{
  "id": "wh_evt_abc123",
  "event": "verification.completed",
  "created_at": "2026-03-20T14:30:00Z",
  "data": {
    "email": "john.doe@example.com",
    "status": "valid",
    "confidence": 97,
    "is_catch_all": false,
    "is_disposable": false,
    "mx_found": true,
    "smtp_check": true
  }
}

The event field tells your application what type of notification this is, while the data object contains the relevant details specific to that event type.

Retry Logic and Failure Handling

Mailsfinder expects your endpoint to respond with an HTTP 2xx status code within 10 seconds. If your server does not respond in time, or returns a non-2xx status, Mailsfinder will retry the delivery using an exponential backoff schedule:

• Retry 1: 30 seconds after initial failure
• Retry 2: 2 minutes after retry 1
• Retry 3: 10 minutes after retry 2
• Retry 4: 1 hour after retry 3
• Retry 5: 6 hours after retry 4 (final attempt)

After 5 failed delivery attempts, the webhook event is marked as failed and logged in your dashboard under Settings > Webhooks > Delivery Log. You can manually retry any failed delivery from that screen.

Testing Your Webhooks

Mailsfinder provides two ways to test webhooks before going live:

• Dashboard test ping: Click the "Send Test" button next to any registered webhook. This sends a sample payload so you can confirm your endpoint processes it correctly.
• Local development with tunneling: Use a tool like ngrok to expose your local development server to the internet. Run ngrok http 3000, then use the generated HTTPS URL as your webhook endpoint in Mailsfinder.

Security Best Practices

Always verify the x-mailsfinder-signature header to confirm that incoming requests genuinely originate from Mailsfinder. Store your webhook secret securely in environment variables, and never hard-code it in your application source. Restrict your webhook endpoint to accept requests only from Mailsfinder's documented IP ranges for an additional layer of protection.