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 betruetimestamp(string, required): ISO 8601 timestamp of receiptwebhookId(string, required): Echo theidfrom 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"
}
}
]
}
Authorizations
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
Was this page helpful?
⌘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"
}
}
]
}