Inbound Webhooks

Implementation

While authenticating your system to initiate requests is a significant part of data exchange, it only enables one side of the data traffic highway, so to speak. It's equally important to configure your system to transmit API requests. At Two Boxes, webhooks:

• Accept POST requests only
• Use SSL/TLS encryption
• Check the verification token of every request to ensure that the request is a legitimate one from a Two Boxes partner

Two Boxes accepts webhook event messages into a queue that are then processed asynchronously:

While Two Boxes aims to have zero down-time, transient networking issues, data center outages, and Two Boxes maintenance windows can occur. Ideally, event producers will:

• Retry a failed webhook (any non-2xx HTTP status response) up to 15 times with an 2x exponential backoff delay
• Ensure that each inbound event ID is unique to help with idempotency and retries

Webhook Structure

Endpoint

• https://api.twoboxes.io/webhooks/{id} provided by Two Boxes

Headers

Event Envelope

Event Types

Return Initiated

• Broadcast when a shopper has initiated a return. Will create a return and return line items in the Two Boxes system, ready to be scanned and graded at a 3PL facility.

Shipping Label Created

• Broadcast when a shipping label is assigned at point after the RMA is initiated. Use this event to notify the 3PL that the return is on its way.

Simulate Grading

• Broadcast to assign a Two Boxes disposition to items in a return. Any ensuing actions that grading the items triggers in the Two Boxes configuration will be executed also.

Return Cancelled

• Broadcast when either the shopper or the RMA provider has cancelled the return. Two Boxes should not process the return.

Errors

Lifecycle