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:**
    ```json
            {
              "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](#operation/regenerateAccountSecret) endpoint.

---

### Client Response Format (Required)

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

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

<details> <summary><strong>Response Requirements</strong></summary> </details> <details> <summary><strong>Field Descriptions & Implementation Guide</strong></summary>

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

</details>

----

{
  "defaults": {
    "url": "https://example.com/webhooks/lusha",
    "entityType": "contact",
    "signalTypes": [
      "promotion"
    ]
  },
  "name": "Contact Webhook",
  "subscriptions": [
    {
      "entityId": "123"
    }
  ]
}

{
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "success": true,
      "subscription": {
        "id": "507f1f77bcf86cd799439011",
        "entityType": "contact",
        "entityId": "123456",
        "signalTypes": [
          "promotion",
          "companyChange"
        ],
        "url": "https://example.com/webhooks/lusha",
        "name": "Contact Promotion Tracker",
        "isActive": true,
        "blockReason": "Max retries exceeded",
        "blockedAt": "2026-01-14T10:00:00.000Z",
        "createdAt": "2026-01-14T10:00:00.000Z",
        "updatedAt": "2026-01-14T10:00:00.000Z"
      }
    }
  ]
}