Skip to content
Last updated

Webhooks

Overview

Our webhooks provide real-time notifications for key events in the return process. They help e-commerce businesses automate responses throughout the return lifecycle. By subscribing, you receive instant updates when return statuses change — including creation, shipping, completion, cancellation, and refunds.

Security and Authentication

Webhooks trigger public endpoints, and it is expected that the client validates incoming requests. Each webhook includes an X-REVER-Signature HTTP header — a Hmac-SHA256 string generated using the payload and a shared secret given during registration.

Payload Reference

This section shows a single reference payload example at the top of the document. It is based on the On Return Process Creation webhook, which is the most complete payload shape.

Payload fields

  • rever_process_id: Unique return process identifier.
  • rever_process_status: Status of the return (RUNNING, COMPLETED, FAILED, CANCELED, ON_HOLD)
  • portal_name: Name of the returns portal used.
  • platform_process_id: Upstream platform reference for the process.
  • started_at: ISO-8601 creation timestamp.
  • order_id: Internal order ID.
  • order_name: Customer-facing order name/number.
  • shopper: Customer contact details.
    • email
    • first_name
    • last_name
    • phone_number
  • return_line_items: Products being returned with amounts and taxation.
    • per item: id, return_reason, product (product_id, variant_id, sku, ean, name, variant_name), quantity, unit_price, subtotal_price, total_discounts, total_taxes, total_price, currency, compensation_method
  • reviews: Array with review outcomes per line item.
    • per review: line_item_id, reject_reason, status, review_date, user
  • compensation: Resolution details.
    • refunds: Array of refunds with amount, currency, refunded_at, missing_amount, type.
    • exchange_order: Replacement order details with order info, shipping_address, and ordered_items.
  • logistics: Array with shipping/tracking info for the return.
    • per entry: tracking_number, tracking_url, status, carrier, method, from, to
  • return_costs: Array of return-related cost components; amounts in cents.
    • per entry: type, total, currency

Example Payload

{
  "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": [
    {
      "line_item_id": "rli_tshirt_01",
      "reject_reason": null,
      "status": "APPROVED",
      "review_date": "2025-08-12T11:05:21Z",
      "user": "returns_agent_01"
    },
    {
      "line_item_id": "rli_tshirt_01",
      "reject_reason": "ITEM_WORN",
      "status": "REJECTED",
      "review_date": "2025-08-12T11:05:21Z",
      "user": "returns_agent_01"
    },
    {
      "line_item_id": "rli_jeans_01",
      "reject_reason": null,
      "status": "APPROVED",
      "review_date": "2025-08-12T11:05:21Z",
      "user": "returns_agent_01"
    }
  ],
  "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": "IN_TRANSIT",
      "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"
    }
  ]
}

Webhook Events

On Return Process Creation

This webhook is triggered when a return process is created. It provides detailed data about the return, including products being returned, associated costs, and customer information. Payload shape matches the reference payload above.

On Shipping Status Updated

Triggered when the shipping status of a return is updated. Useful for tracking return progress.

Status values:

  • NO_SHIPPING_STATUS_UNSPECIFIED
  • SHIPPING_STATUS_CREATED
  • SHIPPING_STATUS_COLLECTED
  • SHIPPING_STATUS_IN_WAREHOUSE
  • SHIPPING_STATUS_ERROR
  • SHIPPING_STATUS_CANCELED

On Process Completed

Triggered when a return process is completed — return received, inspected, and resolved.

On Return Process Canceled

Triggered when a return process is canceled. Useful for updating systems and inventory.

 
 
REVER all rights reserved.