rewio-ru Webhooks API

openapi: 3.2.0
info:
  title: Review Aggregator Webhooks API
  description: 'Единый REST API для отзывов: сервис собирает отзывы с площадок (Яндекс Карты, 2ГИС, Google, Островок, ДокДок и др.), приводит их к общей модели и отдаёт с фильтрами и аналитикой.


    📚 **Гайды, quickstart и полный справочник – на портале разработчика: https://docs.rewio.ru**


    #### Как начать

    1. Создайте **объект** – единицу бизнеса, отзывы по которой собираем.

    2. Добавьте в него **ссылки** на страницы объекта на нужных площадках.

    3. Запрашивайте **отзывы** и **аналитику** – данные обновляются дважды в сутки.


    #### Что вы получаете по каждому отзыву

    - **Текст**, **автор**, **оценка** – приведена к единой шкале 1–5 независимо от площадки

    - **Ответ организации** – текст и дата

    - **Изображения и видео** – превью и полноразмерные ссылки


    #### Работа с отзывами

    На тарифе «Полный»:

    - **Ответы** – публикация, замена и удаление ответа от лица организации (на пробном доступе – 3 на площадку)

    - **Жалобы** – подача жалобы на отзыв через форму площадки и её итог (на пробном доступе – 3 на площадку)

    - **Дополнительный сбор** – новые отзывы по объекту вне расписания, раз в сутки (на пробном доступе – 5 сборов)


    #### Соглашения

    - **Базовый URL:** `https://api.rewio.ru`. Актуальная версия – `/v3`.

    - **Авторизация:** заголовок `X-API-Key: ` в каждом запросе. Области ключа: `read_only` / `full`.

    - **Формат:** JSON на вход и выход.

    - **Даты:** UTC, ISO 8601 без таймзоны (`2026-02-25T09:28:07`). Время площадки (`review_date`, `reply_date`) приводится к UTC везде, где это возможно; в противном случае – как на площадке.

    - **Оценки:** нормализованы к единой шкале 1–5 независимо от площадки; исходное значение площадки сохраняется отдельно (`rating_original`).

    - **Списки:** ключ элементов всегда `data`. Постраничные ответы – `{data, total, limit, offset, has_next}` (параметры `limit` 1–1000 и `offset`); полные списки – только `{data}`.

    - **Ошибки:** единый формат `{"detail": "...", "code": "..."}` с машиночитаемым `code`. Отдельно стоит `402`: доступ приостановлен (закончился пробный период или оплата) либо площадка не входит в тариф – повтор запроса не поможет.

    - **Ограничение частоты:** при слишком частых запросах – `429`; повторите с задержкой.


    #### Проба

    В блоке авторизации уже подставлен тестовый ключ (только чтение) – можно сразу выполнить любой GET-запрос.


    **Тестовый ключ (только чтение):** `hrev_FaDGMKJEDDeCR5BCBgEg0aEjMogI7O7hOzE53YY4T1M`

    **Тестовый объект:** Отель Националь, **object_id = 20**


    Бесплатный тестовый доступ на создание 30 объектов.

    **Подключение и доступ:** 📧 info@rewio.ru · ✈️ @const_rewio'
  version: 3.0.0
servers:
- url: https://api.rewio.ru
  description: Production
tags:
- name: Webhooks
  description: 'Вебхуки: уведомления о новых отзывах, новых ответах и завершении сбора.


    **Быстрый старт:**

    1. `POST /v3/webhooks` с `{"target": "https://...", "event_types": ["reviews.new"]}` – создать вебхук.

    2. `POST /v3/webhooks/{id}/test` – тестовая доставка на ваш endpoint.

    3. Принимайте POST-запросы с событием `reviews.new` (дайджест новых отзывов по вашим объектам); отвечайте `2xx`.

    4. Отвечайте `2xx` быстро. Недоставленные события мы повторяем сами, а не доставленное после всех попыток пишем вам письмом.


    **Секрет подписи – один на аккаунт** (виден всегда): `GET /v3/webhooks/secret`; перевыпуск – `POST /v3/webhooks/rotate-secret` (старый действует ещё 24ч).


    **Проверка подписи** (опциональна, но рекомендуется): заголовок `X-Hrev-Signature: sha256=`, где `hex = HMAC_SHA256(secret, "{X-Hrev-Timestamp}." + raw_body)`. Сравнивайте constant-time-функцией; отклоняйте запросы, у которых `|now − X-Hrev-Timestamp| > 300` секунд. Дедуплицируйте по `X-Hrev-Delivery-Id` (при ретраях один дайджест может прийти дважды). Отвечайте 2xx в течение 10 секунд; 5xx/408/429/таймаут – будет ретрай по нарастающей лестнице (30с → 30м, до 30 попыток за ~12ч), прочие 4xx – доставка помечается failed без ретраев. Подписка сама не отключается при неуспешных доставках.'
paths:
  /v3/webhooks:
    get:
      tags:
      - Webhooks
      summary: Список вебхуков
      description: Все ваши подписки со статусом и счётчиком неудач.
      operationId: list_webhooks_v3_v3_webhooks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnAll_WebhookV3_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
    post:
      tags:
      - Webhooks
      summary: Создать вебхук
      description: 'Подписаться на события: новые отзывы, новые ответы, конец цикла сбора.


        `object_ids` сужает подписку до перечисленных объектов; без него события

        приходят по всем вашим. Подпись доставки проверяется секретом аккаунта –

        он один на все ваши подписки, см. `GET /v3/webhooks/secret`.'
      operationId: create_webhook_v3_v3_webhooks_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateV3'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
  /v3/webhooks/secret:
    get:
      tags:
      - Webhooks
      summary: Секрет подписи аккаунта
      description: 'Секрет, которым подписаны все доставки аккаунта. Первый вызов его создаёт.


        Требует ключ со scope `full`: секрет проверяет

        подпись доставок, ключу «только чтение» он не полагается.'
      operationId: get_account_secret_v3_v3_webhooks_secret_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountSecretResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
  /v3/webhooks/rotate-secret:
    post:
      tags:
      - Webhooks
      summary: Перевыпустить секрет аккаунта
      description: 'Выпустить новый секрет. Старый действует ещё 24 часа: за это время обновите

        проверку подписи на своей стороне.'
      operationId: rotate_account_secret_v3_v3_webhooks_rotate_secret_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountSecretResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
  /v3/webhooks/{webhook_id}:
    patch:
      tags:
      - Webhooks
      summary: Изменить вебхук
      description: 'Изменить подписку: адрес, состав объектов, события, окно, фильтры,

        включённость. Передавайте только то, что меняется.'
      operationId: update_webhook_v3_v3_webhooks__webhook_id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
          title: Webhook Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdateV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Webhooks
      summary: Удалить вебхук
      description: Удалить подписку. Доставки по ней прекращаются сразу.
      operationId: delete_webhook_v3_v3_webhooks__webhook_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
          title: Webhook Id
      responses:
        '204':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/webhooks/{webhook_id}/test:
    post:
      tags:
      - Webhooks
      summary: Тестовая доставка
      description: Отправить на ваш адрес тестовое событие – проверить доступность и подпись.
      operationId: test_webhook_v3_v3_webhooks__webhook_id__test_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: integer
          title: Webhook Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSubscriptionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TestSubscriptionResponse:
      properties:
        status:
          type: string
          const: queued
          title: Status
        test_id:
          type: string
          title: Test Id
      type: object
      required:
      - status
      - test_id
      title: TestSubscriptionResponse
    ReturnAll_WebhookV3_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WebhookV3'
          type: array
          title: Data
          description: Все элементы (пагинации нет).
      type: object
      required:
      - data
      title: ReturnAll[WebhookV3]
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
        code:
          type: string
          title: Code
      type: object
      required:
      - detail
      - code
      title: ErrorResponse
      description: Standard error response returned by all exception handlers.
    WebhookCreateV3:
      properties:
        target:
          type: string
          maxLength: 500
          title: Target
          description: HTTPS-адрес, на который приходят события.
        object_ids:
          anyOf:
          - items:
              type: integer
            type: array
            maxItems: 200
            minItems: 1
          - type: 'null'
          title: Object Ids
          description: Присылать события только по этим объектам. Не передано – по всем вашим.
        event_types:
          items:
            type: string
            enum:
            - reviews.new
            - replies.new
            - scrape.run.finished
          type: array
          maxItems: 10
          minItems: 1
          title: Event Types
          description: Какие события присылать.
        bucket_window:
          type: string
          title: Bucket Window
          description: Как часто собирать события в одну доставку.
          default: immediate
          examples:
          - immediate
          - daily_9
          - daily_14
        filters:
          $ref: '#/components/schemas/FiltersV2'
          description: 'Что именно присылать: оценки, площадки, наличие текста и картинок.'
      type: object
      required:
      - target
      - event_types
      title: WebhookCreateV3
      description: Создание подписки на события.
      example:
        bucket_window: immediate
        event_types:
        - reviews.new
        object_ids:
        - 20
        target: https://example.com/hooks/rewio
    AccountSecretResponse:
      properties:
        secret:
          type: string
          title: Secret
        rotated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Rotated At
      type: object
      required:
      - secret
      title: AccountSecretResponse
      description: 'Account-level webhook signing secret. Returned by `GET

        /webhooks/secret` (always) and `POST /webhooks/rotate-secret`.'
      examples:
      - secret: whsec_...
      example:
        secret: whsec_...
    FiltersV2:
      properties:
        allowed_ratings:
          items:
            type: integer
          type: array
          title: Allowed Ratings
        allowed_sources:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Sources
        has_text:
          type: boolean
          title: Has Text
          default: false
        has_images:
          type: boolean
          title: Has Images
          default: false
      type: object
      title: FiltersV2
      description: Фильтры доставки; условия объединяются по AND.
      examples:
      - allowed_ratings:
        - 1
        - 2
        allowed_sources:
        - yandex_maps
        has_images: false
        has_text: true
      example:
        allowed_ratings:
        - 1
        - 2
        allowed_sources:
        - yandex_maps
        has_images: false
        has_text: true
    WebhookUpdateV3:
      properties:
        target:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Target
          description: Новый адрес доставки.
        object_ids:
          anyOf:
          - items:
              type: integer
            type: array
            maxItems: 200
            minItems: 1
          - type: 'null'
          title: Object Ids
          description: Новый список объектов.
        event_types:
          anyOf:
          - items:
              type: string
              enum:
              - reviews.new
              - replies.new
              - scrape.run.finished
            type: array
            maxItems: 10
            minItems: 1
          - type: 'null'
          title: Event Types
          description: Новый набор событий.
        bucket_window:
          anyOf:
          - type: string
            description: Delivery cadence. `immediate` – one POST shortly after each scrape batch; `daily_<hour>` – one digest per day at the given UTC hour (0–23), e.g. `daily_9` = 09:00 UTC, `daily_14` = 14:00 UTC.
            examples:
            - immediate
            - daily_9
            - daily_14
          - type: 'null'
          title: Bucket Window
          description: Новое окно группировки.
        filters:
          anyOf:
          - $ref: '#/components/schemas/FiltersV2'
          - type: 'null'
          description: Новые фильтры.
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: Включить или выключить подписку.
      type: object
      title: WebhookUpdateV3
      description: Изменение подписки – передавайте только изменяемые поля.
    WebhookV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор подписки.
        target:
          type: string
          title: Target
          description: Адрес доставки.
        object_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Object Ids
          description: Объекты, по которым приходят события. `null` – по всем.
        event_types:
          items:
            type: string
            enum:
            - reviews.new
            - replies.new
            - scrape.run.finished
          type: array
          title: Event Types
          description: События подписки.
        bucket_window:
          type: string
          title: Bucket Window
          description: Окно группировки событий в одну доставку.
        filters:
          $ref: '#/components/schemas/FiltersV2'
          description: Фильтры выдачи событий.
        is_active:
          type: boolean
          title: Is Active
          description: Включена ли подписка.
        failure_count:
          type: integer
          title: Failure Count
          description: Сколько неудачных доставок подряд.
        last_failure_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Failure At
          description: Момент последней неудачи (UTC, ISO 8601).
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Момент создания подписки (UTC, ISO 8601).
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Момент последнего изменения (UTC, ISO 8601).
      type: object
      required:
      - id
      - target
      - event_types
      - bucket_window
      - filters
      - is_active
      - failure_count
      - created_at
      - updated_at
      title: WebhookV3
      description: Подписка на события.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    APIKeyCookie:
      type: apiKey
      in: cookie
      name: rewio_session