{
  "name": "Nika AI Webhook Receiver Contract",
  "version": "2026-07-29",
  "language": "ru",
  "purpose": "Integration contract for the endpoint that receives accepted Nika AI leads from Sites.",
  "source_api": "https://agentnika.ru/api/leads",
  "integrations_page": "https://agentnika.ru/integrations",
  "lead_schema": "https://agentnika.ru/lead-schema.json",
  "lead_ops": "https://agentnika.ru/lead-ops.json",
  "method": "POST",
  "content_type": "application/json",
  "required_request_headers": [
    {
      "name": "Content-Type",
      "value": "application/json",
      "reason": "The webhook body is an accepted lead payload."
    },
    {
      "name": "Idempotency-Key",
      "value": "<leadId>",
      "reason": "Receiving systems should use this key to deduplicate retries and repeated submissions."
    }
  ],
  "optional_request_headers": [
    {
      "name": "Authorization",
      "value": "Bearer <NIKA_LEAD_WEBHOOK_TOKEN>",
      "reason": "Sent only when the optional Sites environment variable is configured."
    }
  ],
  "required_payload_fields": [
    "leadId",
    "name",
    "contact",
    "business",
    "task",
    "consent",
    "receivedAt",
    "status",
    "summaryText"
  ],
  "recommended_payload_fields": [
    "source",
    "sourcePath",
    "sourceUrl",
    "referrer",
    "utmSource",
    "utmMedium",
    "utmCampaign",
    "utmContent",
    "utmTerm",
    "interest",
    "preferredChannel",
    "consentText"
  ],
  "success_response": {
    "status_codes": [200, 201, 202, 204],
    "body_required": false,
    "meaning": "The receiving endpoint accepted the lead and Nika AI can report delivery: delivered."
  },
  "failure_response": {
    "status_codes": "non-2xx",
    "meaning": "Nika AI reports delivery: webhook_failed and keeps the visitor-facing fallback summary available."
  },
  "deduplication_rule": "Store or compare leadId and Idempotency-Key. If the same key arrives again, do not create a duplicate lead; update the existing record or return a 2xx response.",
  "owner_display_rule": "Show summaryText to the owner first, then keep structured fields for filtering, routing, campaign attribution, and follow-up.",
  "production_ready_example": {
    "request_headers": {
      "Content-Type": "application/json",
      "Idempotency-Key": "lead_test_product_card_generator_001",
      "Authorization": "Bearer <optional token>"
    },
    "payload_excerpt": {
      "leadId": "lead_test_product_card_generator_001",
      "status": "accepted",
      "interest": "Генератор карточек товара",
      "sourcePath": "/products/product-card-generator",
      "sourceUrl": "/products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot",
      "utmSource": "telegram",
      "utmCampaign": "first-pilot",
      "summaryText": "Заявка Nika AI\nID заявки: lead_test_product_card_generator_001\nИмя: Тест\nКонтакт: test@example.com\nБизнес: Маркетплейс\nИнтерес: Генератор карточек товара\nКанал ответа: Telegram\nСтраница: /products/product-card-generator\nИсточник: /products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot\nКампания: source=telegram; medium=social; campaign=first-pilot\nЗадача: Проверить генератор карточек товара\nСогласие на обработку персональных данных: получено"
    },
    "expected_response": {
      "status": 204
    }
  }
}