{ "opencollection": "1.0.0", "info": { "name": "Lusha API Documentation Webhooks API" }, "request": { "auth": { "type": "apikey", "key": "api_key", "value": "{{api_key}}", "placement": "header" } }, "items": [ { "info": { "name": "Webhooks", "type": "folder" }, "items": [ { "info": { "name": "List Subscriptions", "type": "http" }, "http": { "method": "GET", "url": "https://api.lusha.com/api/subscriptions", "params": [ { "name": "limit", "value": "10", "type": "query", "description": "Maximum number of results (1-100)" }, { "name": "offset", "value": "0", "type": "query", "description": "Number of results to skip" } ] }, "docs": "Returns all webhook subscriptions for your account with pagination support.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/subscriptions**\n\n**Pagination:**\n- Results are sorted by `createdAt` in descending order (newest first)\n- Default limit: 10, max limit: 100\n- Use `offset` for pagination through large result sets\n\n> **Note:** The webhook `secret` is never returned in list responses for security.\n" }, { "info": { "name": "Create Subscription", "type": "http" }, "http": { "method": "POST", "url": "https://api.lusha.com/api/subscriptions", "body": { "type": "json", "data": "{}" } }, "docs": "Creates one or more webhook subscriptions for real-time signal notifications.\n\n**Delivery & Reliability:**\n- Webhooks are delivered with automatic retry on failures\n- Maximum 3 retry attempts with exponential backoff\n- Subscriptions auto-disable after max retries exceeded\n- All deliveries are logged in audit logs\n\n> **Note:** Your webhook endpoint must respond with a proper acknowledgment. \n See Client Response Format below for details.\n\n> **Limit:** Maximum 25 subscriptions per request\n\n*Endpoi" }, { "info": { "name": "Get Subscription by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.lusha.com/api/subscriptions/:id", "params": [ { "name": "id", "value": "507f1f77bcf86cd799439011", "type": "path", "description": "Subscription ID" } ] }, "docs": "Returns a single webhook subscription by ID.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/subscriptions/{id}**\n" }, { "info": { "name": "Update Subscription", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.lusha.com/api/subscriptions/:id", "params": [ { "name": "id", "value": "507f1f77bcf86cd799439011", "type": "path", "description": "Subscription ID" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing webhook subscription. All fields are optional.\n\n*Endpoint*: **(PATCH) https://api.lusha.com/api/subscriptions/{id}**\n\n---\n**Reactivating Disabled Subscriptions:**\n\nWhen setting `isActive: true` on a previously disabled subscription, the system automatically:\n- Clears the `blockReason` field\n- Clears the `blockedAt` timestamp\n- Resets the retry counter\n\n**Regenerating Secrets:**\n\nSet `regenerateSecret: true` to generate a new webhook secret. The new secret:\n- Affects **all sub" }, { "info": { "name": "Test Subscription", "type": "http" }, "http": { "method": "POST", "url": "https://api.lusha.com/api/subscriptions/:id/test", "params": [ { "name": "id", "value": "507f1f77bcf86cd799439011", "type": "path", "description": "Subscription ID" }, { "name": "mode", "value": "full", "type": "query", "description": "Test mode" } ] }, "docs": "Test a webhook subscription by sending a test signal. Supports three test modes.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/{id}/test**\n---\n**Test Modes:**\n- `direct` - Quick HTTP check only (validates URL responds correctly)\n- `kafka` - Fanout handler only (tests Kafka message processing)\n- `full` - Complete Kafka flow (default - end-to-end test)\n\n**Important Notes:**\n- Test deliveries do NOT consume credits\n- Test payloads use mock data\n- Useful for verifying webhook configu" }, { "info": { "name": "Delete Subscriptions", "type": "http" }, "http": { "method": "POST", "url": "https://api.lusha.com/api/subscriptions/delete", "body": { "type": "json", "data": "{}" } }, "docs": "Delete one or more webhook subscriptions. Returns detailed results for each deletion with partial success support.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/delete**\n\n---\n\n**Behavior:**\n- Each subscription is processed independently\n- Returns detailed results for each item including deleted subscription info\n- Invalid ID formats are gracefully handled and reported as NOT_FOUND\n- Duplicate IDs are automatically deduplicated\n- Deletion is permanent and cannot be undone\n" }, { "info": { "name": "Get Audit Logs", "type": "http" }, "http": { "method": "GET", "url": "https://api.lusha.com/api/audit-logs", "params": [ { "name": "subscriptionId", "value": "507f1f77bcf86cd799439011", "type": "query", "description": "Filter by subscription ID" }, { "name": "status", "value": "success", "type": "query", "description": "Filter by delivery status" }, { "name": "limit", "value": "50", "type": "query", "description": "Maximum number of results (1-100)" }, { "name": "offset", "value": "0", "type": "query", "description": "Number of results to skip" } ] }, "docs": "Retrieve webhook delivery logs for your account.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/audit-logs**\n\n**What's Logged:**\n- All webhook delivery attempts (success and failures)\n- HTTP status codes and response times\n- Error messages for failed deliveries\n- Delivery timestamps and duration metrics\n\n**Filtering:**\n- Filter by subscription ID to see logs for specific subscriptions\n- Filter by status to see only successes, failures, or permanent failures\n\n**Rate Limit:** 100 requests/minute p" }, { "info": { "name": "Get Audit Log Statistics", "type": "http" }, "http": { "method": "GET", "url": "https://api.lusha.com/api/audit-logs/stats", "params": [ { "name": "subscriptionId", "value": "sub-123", "type": "query", "description": "Filter statistics by subscription ID" } ] }, "docs": "Get delivery statistics for your account.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/audit-logs/stats**\n" }, { "info": { "name": "Get Account Secret", "type": "http" }, "http": { "method": "GET", "url": "https://api.lusha.com/api/account/secret" }, "docs": "Retrieve the current account webhook secret.\n\n*Endpoint*: **(GET) https://api.lusha.com/api/account/secret**\n" }, { "info": { "name": "Regenerate Account Secret", "type": "http" }, "http": { "method": "POST", "url": "https://api.lusha.com/api/account/secret/regenerate" }, "docs": "Regenerate the account webhook secret. Affects **all subscriptions** for the account.\n\n*Endpoint*: **(POST) https://api.lusha.com/api/account/secret/regenerate**\n\n**Behavior:**\n- If a secret already exists: Replaces with new secret (old secret is invalidated)\n- If no secret exists: Creates new secret automatically\n\n**Important Notes:**\n- The secret is only shown once in the response. Store it securely.\n- This endpoint always succeeds (upsert operation)\n- Regenerating invalidates the old secret f" }, { "info": { "name": "Create Opt-Out Subscription", "type": "http" }, "http": { "method": "POST", "url": "https://api.lusha.com/api/subscriptions/opt-out", "body": { "type": "json", "data": "{}" } }, "docs": "Subscribe to real-time notifications when a contact opts out of data processing. When a contact requests removal, Lusha sends an `OptOutWebhookPayload` to your endpoint so you can action the removal in your own systems (CRM, outreach tools, etc.).\n\n*Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/opt-out**\n\n---\n\n**How it works:**\n- Create one opt-out subscription per account (scoped to `contact` entity type)\n- Lusha delivers a POST request to your URL whenever a contact opts out\n- Th" } ] } ], "bundled": true }