Welcome to Tomba Docs! Create a free Tomba accountand gain instant access to 400+ million contacts!
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:

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

Field Descriptions

FieldTypeDescription
emailstringLead's email address
websitestringWebsite URL
company*stringCompany name
first_name*stringLead's first name
last_name*stringLead's last name
phone*stringPhone number
position*stringJob position
twitter*stringTwitter handle
linkedin*stringLinkedIn profile URL
notes*stringAdditional notes about the lead
scoreintegerLead score (numeric value)

Example Implementation

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

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");
});
javascript

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