{ "openapi": "3.1.0", "info": { "title": "Webhooks", "version": "1.1.0", "description": "## Summary\n### Introduction\n\nREVER webhooks provide real-time notifications for key events in the return process. They allow businesses to automate responses throughout the return lifecycle.\n
By subscribing, you receive instant updates when return statuses change — including\ncreation, shipping updates, completion, and cancellations.\n\n\n## Registration\n\nTo start receiving webhooks, contact your account manager to register your endpoint URL\nand obtain the shared secret used for signature verification.\n\n## Security and Authentication\n\nWebhooks are sent to public endpoints — your server is responsible for validating\nthat each request genuinely comes from REVER.\n\nEvery webhook request includes an **`X-REVER-Signature`** HTTP header containing\na **HMAC-SHA256** signature. To verify it:\n\n1. Retrieve the raw request body (as a string, before any parsing).\n2. Compute `HMAC-SHA256(body, sharedSecret)` using the shared secret provided\n during registration.\n3. Compare your computed signature against the value in `X-REVER-Signature`.\n Reject the request if they do not match.\n" }, "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.\n", "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.\n", "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.\n", "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.\n", "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).\n" }, "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.\n" } } } }