# Create Subscription

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

URL Validation:
- The URL is validated once before creating any subscriptions
- Includes format checking and challenge request verification
- If URL validation fails, no subscriptions are created

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

> 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
      }
    }
    

      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.

---

Endpoint: POST /api/subscriptions
Security: ApiKeyAuth

## Request fields (application/json):

  - `defaults` (object, required)

  - `defaults.url` (string, required)
    Webhook URL - validated once with challenge request (HTTPS required in production)
    Example: "https://example.com/webhooks/lusha"

  - `defaults.entityType` (string)
    Default entity type for all subscriptions
    Enum: "contact", "company"

  - `defaults.signalTypes` (array)
    Default signal types for all subscriptions. Available signals depend on entity type:

Examples for contacts:
- promotion - Job title promotions
- companyChange - Company changes
- allSignals - All contact signals

Examples for companies:
- newsEvent - Company-related events and news
- allSignals - All company signals
- surgeInHiring - Overall hiring activity increase

Please refer to the [Signal Options Section](https://docs.lusha.com/apis/openapi/signals/getsignaloptions) for a full list of available signals.
    Example: ["promotion","newsEvent"]

  - `defaults.name` (string)
    Default subscription name prefix
    Example: "Contact Webhook"

  - `subscriptions` (array, required)
    Array of subscriptions to create (max 10 in development, 25 in production)

  - `subscriptions.entityId` (string, required)
    Entity ID (always required per item)
    Example: "123"

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

  - `subscriptions.signalTypes` (array)
    Overrides default signalTypes

  - `subscriptions.name` (string)
    Overrides default name

## Response 201 fields (application/json):

  - `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` (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"]

## Response 401 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"]

## Response 403 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"]

## Response 500 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"]