Copy page

Overview

Webhooks

Overview

Webhooks allow external services to be notified when certain events occur in our system. This documentation covers how to set up a webhook to receive notifications when a lead is saved.

Webhook Configuration

Basic Setup

1. Name your webhook
   Provide a unique name for your webhook (e.g., "Lead Tracking Webhook")

2. Notification URL
   Enter the URL where we should send notifications (e.g., https://your-service.com/webhooks/leads)

3. HTTP Method
   Select the HTTP method used to send the webhook (typically POST)

4. Headers (Optional)
   Add any required headers as key/value pairs (e.g., Authorization tokens)

5. Webhook Status
   Enable or disable the webhook as needed

Supported Events

Currently, we support the following event:

• save_lead: Triggered when a new lead is saved or an existing lead is updated

Notification Payload

When a save_lead event occurs, your webhook will receive a POST request with the following JSON payload:

Code
{
    "data": {
        "email": "",
        "company": "",
        "first_name": "",
        "last_name": "",
        "phone": "",
        "website": "",
        "position": "",
        "twitter": "",
        "linkedin": "",
        "notes": "",
        "score": 0
    }
}

Field Descriptions

Field	Type	Description
email	string	Lead's email address
website	string	Website URL
company	*string	Company name
first_name	*string	Lead's first name
last_name	*string	Lead's last name
phone	*string	Phone number
position	*string	Job position
twitter	*string	Twitter handle
linkedin	*string	LinkedIn profile URL
notes	*string	Additional notes about the lead
score	integer	Lead score (numeric value)

Example Implementation

Here's an example of how you might handle the webhook in a Node.js application:

Code
const express = require("express");
const app = express();

app.post("/webhooks/leads", express.json(), (req, res) => {
    const leadData = req.body.data;
    console.log("Received new lead:", leadData);

    // Process the lead data here

    res.status(200).send("Webhook received");
});

app.listen(3000, () => {
    console.log("Webhook server listening on port 3000");
});

Webhook URL Query Parameter

You can also receive webhook notifications for specific API requests by passing a webhook_url query parameter. This allows you to receive real-time notifications when an operation completes without configuring a global webhook.

Usage

Add the webhook_url parameter to any supported API endpoint:

Code
curl -X GET "https://api.tomba.io/v1/email-verifier?email=john@example.com&webhook_url=https://your-service.com/webhook" \
  -H "X-Tomba-Key: YOUR_API_KEY" \
  -H "X-Tomba-Secret: YOUR_API_SECRET"

Supported Endpoints

The webhook_url query parameter is supported on the following endpoints:

• /email-verifier - Receive verification results
• /email-finder - Receive email finder results
• /domain-search - Receive domain search results
• /author-finder - Receive author finder results
• /phone-finder - Receive phone finder results
• /phone-validator - Receive phone validation results

Webhook Payload

When using the webhook_url query parameter, your endpoint will receive the same response data that would be returned by the API call:

Code
{
    "data": {
        // Response data from the API endpoint
    },
    "meta": {
        "endpoint": "/email-verifier",
        "timestamp": "2026-03-28T10:30:00Z"
    }
}

Notes

• The webhook URL must be a valid HTTPS URL
• The webhook is sent as a POST request with JSON content type
• The API response is returned immediately; the webhook is sent asynchronously
• Failed webhook deliveries are retried up to 3 times with exponential backoff

Best Practices

1. Always validate the incoming webhook data
2. Implement proper error handling
3. Consider adding authentication (e.g., via headers)
4. Respond quickly (within a few seconds) to avoid timeout issues
5. Implement retry logic for failed webhook deliveries