# 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 details summary 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 ```json { "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" } ] } ``` details summary 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 ```json { "order_id": "123456", "return_process_id": "retp_2sCSBt7Z...", "status": "SHIPPING_STATUS_CREATED" } ``` details summary 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 ```json { "order_id": "123456", "return_process_id": "retp_2sCSBt7Z..." } ``` details summary 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 ```json { "order_id": "123456", "return_process_id": "retp_2sCSBt7Z..." } ``` details summary 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 ```json [ { "order_id": "11663146942790", "return_process_id": "retp_2sCSBt7Z...", "refunded_amount": 10900, "currency": "EUR" } ] ```