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


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

  

----

Endpoint: POST /api/subscriptions
Security: ApiKeyAuth

## Request fields (application/json):

  - `defaults` (object, required)

  - `defaults.url` (string, required)
    Example: "https://example.com/webhooks/lusha"

  - `defaults.entityType` (string)
    Enum: "contact", "company"

  - `defaults.signalTypes` (array)
    Default signal types for all subscriptions. Available signals depend on entity type.
Please refer to the Signal Options endpoint for a full list of available signals.
    Example: ["promotion"]

  - `name` (string)
    Example: "Contact Webhook"

  - `subscriptions` (array, required)

  - `subscriptions.entityId` (string, required)
    Example: "123"

  - `subscriptions.entityType` (string)
    Enum: "contact", "company"

  - `subscriptions.signalTypes` (array)

  - `subscriptions.name` (string)

## Response 201 fields (application/json):

  - `total` (integer, required)
    Example: 3

  - `successful` (integer, required)
    Example: 2

  - `failed` (integer, required)
    Example: 1

  - `results` (array, required)

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]