Webhooks

Create Subscription

Creates one or more webhook subscriptions for real-time signal notifications.

Delivery & Reliability:

Webhooks are delivered with automatic retry on failures
Maximum 3 retry attempts with exponential backoff
Subscriptions auto-disable after max retries exceeded
All deliveries are logged in audit logs

Note: Your webhook endpoint must respond with a proper acknowledgment. See Client Response Format below for details.

Limit: Maximum 25 subscriptions per request

Endpoint: (POST) https://api.lusha.com/api/subscriptions

Webhook Payload You’ll Receive

When a signal is triggered, this payload is sent to your webhook URL:

    {
      "id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c",
      "type": "promotion",
      "entityType": "contact",
      "entityId": "4158887495",
      "subscriptionId": "507f1f77bcf86cd799439011",
      "data": {
        "personId": 4158887495,
        "currentCompanyId": 40823133,
        "currentCompanyName": "OMG Hospitality Group LLC",
        "currentDomain": "omghospitalitygroup.com",
        "currentTitle": "Bartender",
        "currentDepartments": [
          { "id": 7, "value": "Other" }
        ],
        "previousCompanyName": "First Watch Restaurants",
        "previousDomain": "firstwatch.com",
        "signalDate": "2025-07-01"
      },
      "timestamp": "2026-01-14T16:16:35.841Z",
      "billing": {
        "creditsCharged": 1
      }
    }

Example — Company News Signal:

        {
          "id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45",
          "type": "commercialActivityNews",
          "entityType": "company",
          "entityId": "33222678",
          "subscriptionId": "507f1f77bcf86cd799439011",
          "data": {
            "companyId": "33222678",
            "companyName": "Lusha",
            "domain": "lusha.com",
            "signalId": "1503910",
            "eventType": "partnership",
            "eventSummary": "Lusha announced a strategic partnership with Salesforce.",
            "articlePublishedDate": "2025-06-15",
            "articleTitle": "Lusha Partners with Salesforce",
            "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.",
            "eventEffectiveDate": "2025-06-10",
            "articleUrl": "https://example.com/lusha-salesforce-partnership"
          },
          "timestamp": "2026-01-14T16:16:35.841Z",
          "billing": {
            "creditsCharged": 1
          }
        }

Headers Included:

Header	Description
`X-Lusha-Signature`	HMAC-SHA256 signature for verification
`X-Lusha-Timestamp`	Unix timestamp of the request
`Content-Type`	application/json
`User-Agent`	Lusha-Webhooks/1.0

⚠️ Important: Ensure your account has a webhook secret before creating subscriptions. Create one via the Regenerate Account Secret endpoint.

Client Response Format (Required)

When your webhook endpoint receives a delivery, it must acknowledge receipt with this response:

Required Response:

{
  "received": true,
  "timestamp": "2026-02-05T10:30:45.123Z",
  "webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c"
}

Response Requirements

Requirement	Value
HTTP Status	`201 Created` (recommended) or any `2xx` status
Content-Type	`application/json`
Response Time	Within 10 seconds

Field Descriptions & Implementation Guide

Field Descriptions:

received (boolean, required): Confirmation flag - must be true
timestamp (string, required): ISO 8601 timestamp of receipt
webhookId (string, required): Echo the id from webhook payload

Implementation Example:

app.post('/webhook', async (req, res) => {
  // 1. Verify signature
  if (!verifyWebhookSignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Queue for async processing
  await queueWebhook(req.body);
  
  // 3. Acknowledge immediately
  res.status(201).json({
    received: true,
    timestamp: new Date().toISOString(),
    webhookId: req.body.id
  });

Important Notes:

Return acknowledgment before heavy processing
Non-2xx responses trigger retry mechanism
After 3 failed retries, subscription is disabled

POST

api

subscriptions

curl --request POST \
  --url https://api.lusha.com/api/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "defaults": {
    "entityType": "contact",
    "signalTypes": [
      "promotion",
      "companyChange"
    ],
    "url": "https://example.com/webhooks/lusha"
  },
  "subscriptions": [
    {
      "entityId": "123456",
      "name": "My Test Webhook"
    }
  ]
}
'

{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 123",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    },
    {
      "index": 1,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439012",
        "entityType": "contact",
        "entityId": "456",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 456",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    },
    {
      "index": 2,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439013",
        "entityType": "contact",
        "entityId": "789",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 789",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    }
  ]
}

Authorizations

api_key

string

header

required

Your Lusha API key. You can find this in your Lusha dashboard under API settings.

Include this key in the api_key header for all requests.

Body

application/json

defaults

object

required

Show child attributes

Example:

["promotion"]

subscriptions

object[]

required

Array of subscriptions to create (max 10 in development, 25 in production)

Required array length: 1 - 25 elements

Show child attributes

name

string

Default subscription name prefix

Maximum string length: 100

Example:

"Contact Webhook"

Response

Subscriptions created (full or partial success)

total

integer

required

Total number of subscription creation attempts

Example:

3

successful

integer

required

Number of successfully created subscriptions

Example:

2

failed

integer

required

Number of failed subscription attempts

Example:

1

results

object[]

required

Option 1
Option 2

Show child attributes

⌘I

curl --request POST \
  --url https://api.lusha.com/api/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "defaults": {
    "entityType": "contact",
    "signalTypes": [
      "promotion",
      "companyChange"
    ],
    "url": "https://example.com/webhooks/lusha"
  },
  "subscriptions": [
    {
      "entityId": "123456",
      "name": "My Test Webhook"
    }
  ]
}
'

{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 123",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    },
    {
      "index": 1,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439012",
        "entityType": "contact",
        "entityId": "456",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 456",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    },
    {
      "index": 2,
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439013",
        "entityType": "contact",
        "entityId": "789",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact 789",
        "isActive": true,
        "createdAt": "2026-02-02T10:00:00.000Z",
        "updatedAt": "2026-02-02T10:00:00.000Z"
      }
    }
  ]
}

Overview

Resources

Endpoints

Create Subscription

Webhook Payload You’ll Receive

Client Response Format (Required)

Authorizations

Body

Response