openapi: 3.1.0
info:
  title: Webhooks
  version: 1.1.0
  description: >
    ## Summary

    ### Introduction


    REVER webhooks provide real-time notifications for key events in the return
    process. They allow businesses to automate responses throughout the return
    lifecycle.

    <br>By subscribing, you receive instant updates when return statuses change
    — including

    creation, shipping updates, completion, and cancellations.



    ## Registration


    To start receiving webhooks, contact your account manager to register your
    endpoint URL

    and obtain the shared secret used for signature verification.


    ## Security and Authentication


    Webhooks are sent to public endpoints — your server is responsible for
    validating

    that each request genuinely comes from REVER.


    Every webhook request includes an **`X-REVER-Signature`** HTTP header
    containing

    a **HMAC-SHA256** signature. To verify it:


    1. Retrieve the raw request body (as a string, before any parsing).

    2. Compute `HMAC-SHA256(body, sharedSecret)` using the shared secret
    provided
       during registration.
    3. Compare your computed signature against the value in `X-REVER-Signature`.
       Reject the request if they do not match.
servers:
  - url: https://api.byrever.com
webhooks:
  onReturnProcessCreation:
    post:
      summary: On Return Process Creation
      security:
        - REVER Signature: []
      description: >
        Triggered when a return process is created. Provides detailed data about
        the return, including products being returned, associated costs, and
        customer information. At this stage, `logistics[].status` is `CREATED`
        and `reviews` is empty — warehouse review has not yet taken place.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnProcessPayload'
            example:
              rever_process_id: retp_123abc456def
              rever_process_status: RUNNING
              portal_name: Main Returns Portal
              platform_process_id: ORD-2025-08-10-001
              started_at: '2025-08-10T09:15:00Z'
              order_id: ORD-2025-08-10-001
              order_name: '#1042'
              shopper:
                email: maria.soler@example.com
                first_name: Maria
                last_name: Soler
                phone_number: '+34600123456'
              return_line_items:
                - id: rli_tshirt_01
                  return_reason: I_DON_T_LIKE_IT
                  product:
                    product_id: prod_9a8b7c
                    variant_id: var_9a8b7c_wht_m
                    sku: TSHIRT-WHT-M
                    ean: '5056342178901'
                    name: Organic Cotton Tee
                    variant_name: White / M
                  quantity: 2
                  unit_price: '2999'
                  subtotal_price: '5998'
                  total_discounts: '0'
                  total_taxes: '1260'
                  total_price: '7258'
                  currency: EUR
                  compensation_method: BANK_TRANSFER
                - id: rli_jeans_01
                  return_reason: WRONG_SIZE
                  product:
                    product_id: prod_1a2b3c
                    variant_id: var_1a2b3c_blk_30
                    sku: JEANS-BLK-30
                    ean: '5056342178902'
                    name: High-Waist Skinny Jeans
                    variant_name: Black / 30W
                  quantity: 1
                  unit_price: '7500'
                  subtotal_price: '7500'
                  total_discounts: '0'
                  total_taxes: '1575'
                  total_price: '9075'
                  currency: EUR
                  compensation_method: EXCHANGE
              reviews: []
              compensation:
                refunds:
                  - amount: '3629'
                    currency: EUR
                    refunded_at: null
                    missing_amount: '0'
                    type: bank_transfer
                exchange_order:
                  order_id: EX-ORD-2025-08-12-001
                  order_name: '#E1043'
                  subtotal_price: '7500'
                  total_discounts: '0'
                  total_taxes: '1575'
                  total_price: '9075'
                  currency: EUR
                  shipping_address:
                    first_name: Maria
                    last_name: Soler
                    phone: '+34600123456'
                    address_line_1: Carrer de Balmes, 123
                    address_line_2: 4º 2ª
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08008'
                    country: ES
                  ordered_items:
                    - quantity: 1
                      product:
                        product_id: prod_1a2b3c
                        variant_id: var_1a2b3c_blk_32
                        sku: JEANS-BLK-32
                        ean: '5056342178903'
                        name: High-Waist Skinny Jeans
                        variant_name: Black / 32W
                      unit_price: '75.00'
                      subtotal_price: '7500'
                      total_discounts: '0'
                      total_taxes: '1575'
                      total_price: '9075'
                      currency: EUR
              logistics:
                - tracking_number: CR123456789ES
                  tracking_url: >-
                    https://www.correos.es/es/es/herramientas/localizador/envios/detalle?tracking-number=CR123456789ES
                  status: CREATED
                  carrier: Correos
                  method: drop_off
                  from:
                    first_name: Maria
                    last_name: Soler
                    phone: '+34600123456'
                    address_line_1: Carrer de Balmes, 123
                    address_line_2: 4º 2ª
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08008'
                    country: ES
                  to:
                    first_name: Rever
                    last_name: Logistics
                    phone: '+34930123456'
                    address_line_1: Carrer de la Llacuna, 161
                    address_line_2: Almacén 5
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08018'
                    country: ES
              return_costs:
                - type: ORIGINAL_SHIPPING
                  total: 495
                  currency: EUR
                - type: RETURN_SHIPPING_COST
                  total: 395
                  currency: EUR
      responses:
        '200':
          description: >-
            Acknowledge receipt — return a 200 to confirm the webhook was
            received successfully.
  onShippingStatusUpdated:
    post:
      summary: On Shipping Status Updated
      security:
        - REVER Signature: []
      description: >
        Triggered when the shipping status of a return is updated. Useful for
        tracking return progress. At this stage, `logistics[].status` is
        `COLLECTED` (the carrier has collected the parcel). `reviews` is empty —
        warehouse review has not yet taken place.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnProcessPayload'
            example:
              rever_process_id: retp_123abc456def
              rever_process_status: RUNNING
              portal_name: Main Returns Portal
              platform_process_id: ORD-2025-08-10-001
              started_at: '2025-08-10T09:15:00Z'
              order_id: ORD-2025-08-10-001
              order_name: '#1042'
              shopper:
                email: maria.soler@example.com
                first_name: Maria
                last_name: Soler
                phone_number: '+34600123456'
              return_line_items: []
              reviews: []
              compensation:
                refunds: []
                exchange_order: null
              logistics:
                - tracking_number: CR123456789ES
                  tracking_url: >-
                    https://www.correos.es/es/es/herramientas/localizador/envios/detalle?tracking-number=CR123456789ES
                  status: COLLECTED
                  carrier: Correos
                  method: drop_off
                  from:
                    first_name: Maria
                    last_name: Soler
                    phone: '+34600123456'
                    address_line_1: Carrer de Balmes, 123
                    address_line_2: 4º 2ª
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08008'
                    country: ES
                  to:
                    first_name: Rever
                    last_name: Logistics
                    phone: '+34930123456'
                    address_line_1: Carrer de la Llacuna, 161
                    address_line_2: Almacén 5
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08018'
                    country: ES
              return_costs: []
      responses:
        '200':
          description: >-
            Acknowledge receipt — return a 200 to confirm the webhook was
            received successfully.
  onProcessCompleted:
    post:
      summary: On Process Completed
      security:
        - REVER Signature: []
      description: >
        Triggered when a return process is completed — the return has been
        received, inspected, and resolved. At this stage, `logistics[].status`
        is `IN_WAREHOUSE`. The `reviews` array is populated here for the first
        time: it contains the warehouse agent's decision (approved or rejected)
        for each returned item after physical inspection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnProcessPayload'
            example:
              rever_process_id: retp_123abc456def
              rever_process_status: COMPLETED
              portal_name: Main Returns Portal
              platform_process_id: ORD-2025-08-10-001
              started_at: '2025-08-10T09:15:00Z'
              order_id: ORD-2025-08-10-001
              order_name: '#1042'
              shopper:
                email: maria.soler@example.com
                first_name: Maria
                last_name: Soler
                phone_number: '+34600123456'
              return_line_items: []
              reviews:
                - line_item_id: rli_tshirt_01
                  reject_reason: null
                  status: APPROVED
                  review_date: '2025-08-14T09:45:00Z'
                  user: returns_agent_01
                - line_item_id: rli_jeans_01
                  reject_reason: null
                  status: APPROVED
                  review_date: '2025-08-14T09:45:00Z'
                  user: returns_agent_01
              compensation:
                refunds:
                  - amount: '3629'
                    currency: EUR
                    refunded_at: '2025-08-14T10:00:00Z'
                    missing_amount: '0'
                    type: bank_transfer
                exchange_order: null
              logistics:
                - tracking_number: CR123456789ES
                  tracking_url: >-
                    https://www.correos.es/es/es/herramientas/localizador/envios/detalle?tracking-number=CR123456789ES
                  status: IN_WAREHOUSE
                  carrier: Correos
                  method: drop_off
                  from:
                    first_name: Maria
                    last_name: Soler
                    phone: '+34600123456'
                    address_line_1: Carrer de Balmes, 123
                    address_line_2: 4º 2ª
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08008'
                    country: ES
                  to:
                    first_name: Rever
                    last_name: Logistics
                    phone: '+34930123456'
                    address_line_1: Carrer de la Llacuna, 161
                    address_line_2: Almacén 5
                    city: Barcelona
                    province_state_code: B
                    postal_code: '08018'
                    country: ES
              return_costs: []
      responses:
        '200':
          description: >-
            Acknowledge receipt — return a 200 to confirm the webhook was
            received successfully.
  onReturnProcessCanceled:
    post:
      summary: On Return Process Canceled
      security:
        - REVER Signature: []
      description: >
        Triggered when a return process is canceled. Useful for updating systems
        and inventory.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnProcessPayload'
            example:
              rever_process_id: retp_123abc456def
              rever_process_status: CANCELED
              portal_name: Main Returns Portal
              platform_process_id: ORD-2025-08-10-001
              started_at: '2025-08-10T09:15:00Z'
              order_id: ORD-2025-08-10-001
              order_name: '#1042'
              shopper:
                email: maria.soler@example.com
                first_name: Maria
                last_name: Soler
                phone_number: '+34600123456'
              return_line_items: []
              reviews: []
              compensation:
                refunds: []
                exchange_order: null
              logistics: []
              return_costs: []
      responses:
        '200':
          description: >-
            Acknowledge receipt — return a 200 to confirm the webhook was
            received successfully.
components:
  schemas:
    ReturnProcessPayload:
      type: object
      description: The payload sent with every webhook event.
      properties:
        rever_process_id:
          type: string
          description: Unique return process identifier.
          example: retp_123abc456def
        rever_process_status:
          type: string
          enum:
            - RUNNING
            - COMPLETED
            - FAILED
            - CANCELED
            - ON_HOLD
          description: Status of the return process.
        portal_name:
          type: string
          description: Name of the returns portal used.
        platform_process_id:
          type: string
          description: Upstream platform reference for the process.
        started_at:
          type: string
          format: date-time
          description: ISO-8601 creation timestamp.
        order_id:
          type: string
          description: Internal order ID.
        order_name:
          type: string
          description: Customer-facing order name/number.
        shopper:
          $ref: '#/components/schemas/Shopper'
        return_line_items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnLineItem'
          description: Products being returned with amounts and taxation.
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
          description: >
            Warehouse review outcomes per line item. Empty until the return has
            been physically inspected at the warehouse (usualy populated only in
            the `onProcessCompleted` event).
        compensation:
          $ref: '#/components/schemas/Compensation'
        logistics:
          type: array
          items:
            $ref: '#/components/schemas/LogisticsEntry'
          description: Shipping and tracking information for the return.
        return_costs:
          type: array
          items:
            $ref: '#/components/schemas/ReturnCost'
          description: Return-related cost components; amounts in cents.
    Shopper:
      type: object
      description: Customer contact details.
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        phone_number:
          type: string
    Product:
      type: object
      properties:
        product_id:
          type: string
        variant_id:
          type: string
        sku:
          type: string
        ean:
          type: string
        name:
          type: string
        variant_name:
          type: string
    ReturnLineItem:
      type: object
      properties:
        id:
          type: string
        return_reason:
          type: string
        product:
          $ref: '#/components/schemas/Product'
        quantity:
          type: integer
        unit_price:
          type: string
          description: Amount in cents.
        subtotal_price:
          type: string
          description: Amount in cents.
        total_discounts:
          type: string
          description: Amount in cents.
        total_taxes:
          type: string
          description: Amount in cents.
        total_price:
          type: string
          description: Amount in cents.
        currency:
          type: string
          example: EUR
        compensation_method:
          type: string
          enum:
            - BANK_TRANSFER
            - EXCHANGE
            - STORE_CREDIT
            - VOUCHER
    Review:
      type: object
      properties:
        line_item_id:
          type: string
        reject_reason:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - APPROVED
            - REJECTED
        review_date:
          type: string
          format: date-time
        user:
          type: string
    Refund:
      type: object
      properties:
        amount:
          type: string
          description: Amount in cents.
        currency:
          type: string
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
        missing_amount:
          type: string
        type:
          type: string
    Address:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        province_state_code:
          type: string
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: ES
    OrderedItem:
      type: object
      properties:
        quantity:
          type: integer
        product:
          $ref: '#/components/schemas/Product'
        unit_price:
          type: string
        subtotal_price:
          type: string
        total_discounts:
          type: string
        total_taxes:
          type: string
        total_price:
          type: string
        currency:
          type: string
    ExchangeOrder:
      type: object
      description: Replacement order details.
      properties:
        order_id:
          type: string
        order_name:
          type: string
        subtotal_price:
          type: string
        total_discounts:
          type: string
        total_taxes:
          type: string
        total_price:
          type: string
        currency:
          type: string
        shipping_address:
          $ref: '#/components/schemas/Address'
        ordered_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderedItem'
    Compensation:
      type: object
      description: Resolution details for the return.
      properties:
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        exchange_order:
          oneOf:
            - $ref: '#/components/schemas/ExchangeOrder'
            - type: 'null'
    LogisticsEntry:
      type: object
      description: Shipping and tracking entry for the return.
      properties:
        tracking_number:
          type: string
        tracking_url:
          type: string
          format: uri
        status:
          type: string
          enum:
            - CREATED
            - COLLECTED
            - IN_WAREHOUSE
            - ERROR
            - CANCELED
        carrier:
          type: string
        method:
          type: string
        from:
          $ref: '#/components/schemas/Address'
        to:
          $ref: '#/components/schemas/Address'
    ReturnCost:
      type: object
      description: A cost component associated with the return.
      properties:
        type:
          type: string
          enum:
            - ORIGINAL_SHIPPING
            - RETURN_SHIPPING_COST
        total:
          type: integer
          description: Amount in cents.
        currency:
          type: string
  securitySchemes:
    REVER Signature:
      type: apiKey
      in: header
      name: X-REVER-Signature
      description: >
        Hmac-SHA256 string generated using the payload and a shared secret
        provided during registration. Validate this header on every incoming
        webhook request.
