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.

Webhook Events

On Return Process Creation

On Return Process Creation

Description

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

  • 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": "proc_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_COST",
      "total": 495,
      "currency": "EUR"
    },
    {
      "type": "RETURN_COST",
      "total": 395,
      "currency": "EUR"
    }
  ]
}
On Shipping Status Updated

On Shipping Status Updated

Description

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

Payload

  • order_id: Order ID.
  • return_process_id: Return process ID.
  • status: Current shipping status.

Status Values

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

Example Payload

{
  "order_id": "123456",
  "return_process_id": "retp_2sCSBt7Z...",
  "status": "SHIPPING_STATUS_CREATED"
}
On Process Completed

On Process Completed

Description

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

Payload

  • order_id: Order ID.
  • return_process_id: REVER return process ID.

Example Payload

{
  "order_id": "123456",
  "return_process_id": "retp_2sCSBt7Z..."
}
On Return Process Canceled

On Return Process Canceled

Description

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

Payload

  • order_id: Order ID.
  • return_process_id: REVER return process ID.

Example Payload

{
  "order_id": "123456",
  "return_process_id": "retp_2sCSBt7Z..."
}
On Refund Processed

On Refund Processed

Description

Triggered when a refund related to a return is processed.

Payload

Array of refund transaction objects:

  • order_id: Order ID.
  • return_process_id: REVER return process ID.
  • refunded_amount: Amount refunded in cents.
  • currency: Currency code.

Example Payload

[
  {
    "order_id": "11663146942790",
    "return_process_id": "retp_2sCSBt7Z...",
    "refunded_amount": 10900,
    "currency": "EUR"
  }
]
 
 
REVER all rights reserved.