# 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:

```json
{
    "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:

```javascript
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:

```bash
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:

```json
{
    "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