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

Name	Value
content-type	application/json
x-twoboxes-webhook-token	`{ defined by Two Boxes as shared token }`

Event Envelope

Property	Type	Description
id	string	Unique message ID that can be used to track idempotency
event_type	string	Describes the shape of the event data
event_data	json object	See details of Event Types for schema

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

Condition	Status	Error Code
Event Consumed	201
Event Consumed Previously	204
Post body not parsable JSON	400	INVALID_JSON_CONTENT
Caller not authenticated by API token	401	API_NOT_AUTHENTICATED
Invalid webhook id provided	404	WEBHOOK_NOT_FOUND
Unexpected system error	500	INTERNAL_SYSTEM_ERROR

Lifecycle