Webhook event types for returns status: a reference guide for partner integrations
Webhook event types for returns status are the set of named events areturnz fires over HTTP as a returned parcel moves through receiving, grading, and disposition, each carrying a signed JSON payload so a partner's system knows the instant something changes without polling. areturnz exposes roughly a dozen of these events across the return lifecycle, from return.received through return.disposition.completed, and every event ties back to the same evidence bundle and audit trail visible in the dashboard.
Why event types matter for partner integrations
Most partner integrations fail not because the API is missing data, but because the integration team guesses at what events exist and when they fire. A clean reference saves a week of trial and error. With a 48 hour median cycle from inbound scan to disposition, a parcel can pass through five or six distinct status changes in two days, and a partner system that only polls once an hour will always be behind. Webhooks close that gap and keep a partner's own customer-facing dashboard, inventory system, or accounting feed in sync in near real time.
This is a companion to the isolation mechanics covered in multi-tenant webhook isolation, which explains how events stay scoped to the correct tenant. This article is the event catalog itself: what fires, when, and what is inside the payload.
The core webhook event types
Every event type maps to a step in the physical returns process. The table below is the current reference set partners subscribe against.
| Event type | Fires when | Key payload fields | Typical partner use |
|---|---|---|---|
| return.received | Parcel is scanned in at the facility (NJ-01) | tracking_id, received_at, facility_code, outer_label_photo_url | Close the loop on the customer's return confirmation |
| return.opened | Parcel is opened and contents photographed | item_count, parcel_photo_url, sku_match_status | Trigger quantity verification checks |
| return.grading.started | AI grading model begins evaluating the item | grading_job_id, sku, started_at | Update internal status to "in review" |
| return.graded | AI assigns a condition grade | grade (A/B/C/R), confidence_score, detected_tags, defect_photo_url | Pull grade and confidence into partner reporting |
| return.grade.overridden | An operator overrides the AI grade | original_grade, final_grade, operator_id, override_reason | Flag items for quality review or model feedback |
| return.disposition.assigned | Disposition rules route the item | disposition (restock/liquidate/donate/destroy), rule_id | Kick off restock, liquidation, or donation workflows |
| return.disposition.completed | The physical disposition action finishes | completed_at, destination, certificate_url (if applicable) | Close the return in partner inventory and finance systems |
| return.evidence.bundle.ready | Full evidence bundle is finalized and signed | bundle_id, bundle_url, signature | Attach proof to a dispute or chargeback case |
| return.exception.flagged | A mismatch or anomaly is detected | exception_type, flagged_at, notes | Route to a human queue or alert ops |
| return.webhook.test | Partner triggers a manual test from the dashboard | test_id, sent_at | Verify endpoint connectivity during setup |
Grades follow the standard A, B, C, R scale, and the confidence score on return.graded is the same figure behind the network's roughly 99.6% AI-versus-operator match accuracy across 180K+ returns processed. A low confidence score is often the first signal that a human review or override is coming next.
Anatomy of a webhook payload
Every event shares a common envelope so a partner can route events generically before branching on type. The envelope carries an event id, event type, tenant id, timestamp, and a signature header for verification, with the event-specific fields nested inside a data object. Partners should always verify the signature before trusting payload contents, and should treat the event id as the deduplication key since some events can be delivered more than once under retry.
Required versus optional fields
Fields like event_id, event_type, tenant_id, and created_at are present on every event and will not change shape without a version bump. Fields inside data can vary by event type and, in a few cases, by vertical (apparel, electronics, beauty items carry slightly different detected_tags). Treat unrecognized fields as safe to ignore rather than a parsing failure, since new optional fields get added as grading detail expands.
Subscribing and filtering events
Partners choose which event types they want delivered when they configure an endpoint in the dashboard or via the API. A partner that only cares about final outcomes might subscribe to return.disposition.completed and return.evidence.bundle.ready alone, skipping the intermediate noise of received and opened events. A partner building a live operations view for its own customers typically subscribes to the full set. Subscriptions are scoped per API key, and the granular API key model covered in granular API keys for partner integrations lets a partner limit a given key to read-only event delivery without granting write access to disposition rules.
Retries, delivery guarantees, and idempotency
If an endpoint returns anything other than a 2xx response, areturnz retries delivery on a backoff schedule for a set window before marking the event as failed and surfacing it in the dashboard's delivery log. This means a partner's endpoint can, in rare cases, receive the same event twice. Building idempotent handling around the event_id field avoids double counting a restock or double closing a dispute. Every delivery attempt, successful or not, is logged and available for replay from the dashboard, which matters when an endpoint has downtime during a deploy.
Webhook events versus polling the API
Some integrations still prefer scheduled polling for reconciliation even when webhooks are the primary channel, and that is a reasonable belt-and-suspenders approach rather than a replacement.
| Approach | Latency | Best for |
|---|---|---|
| Webhooks | Near real time, typically seconds after the triggering event | Live status sync, customer notifications, ops dashboards |
| Polling the signed-JSON API | Minutes to hours depending on schedule | Nightly reconciliation, backfilling gaps after downtime |
Common integration patterns
Most partner builds fall into one of three patterns. A customer-facing status page subscribes to the full lifecycle and renders a simplified progress bar from the raw event stream. A finance integration subscribes narrowly to return.disposition.completed to close out inventory and revenue recognition. A trust and safety or dispute workflow subscribes to return.evidence.bundle.ready and pulls the bundle referenced in a sample evidence bundle directly into a case file. Each pattern pulls from the same event catalog, just a different subset.
For the broader context on how partner integrations, tenancy, and onboarding fit together, see the partner playbook pillar, and review current plan limits on pricing before scoping a high-volume webhook subscription.
Frequently asked questions
How many webhook event types does areturnz support?
The current catalog covers roughly a dozen named events spanning receiving, grading, operator overrides, disposition, and evidence bundle readiness. New optional fields get added within existing events more often than entirely new event types, so most integrations stay stable over time.
What happens if my endpoint is down when an event fires?
areturnz retries delivery on a backoff schedule and logs every attempt in the dashboard. Failed deliveries can be replayed manually once the endpoint is back up, so a short outage does not mean a permanently missed event.
Can I subscribe to only some event types?
Yes. Subscriptions are configured per endpoint and per API key, so a partner can request only the events relevant to their integration, such as final disposition and evidence readiness, without receiving every intermediate status change.
Is the confidence score included in the return.graded event?
Yes. The return.graded payload includes the grade (A, B, C, or R), the confidence score, and detected tags, the same data points behind the network's roughly 99.6% AI-versus-operator match accuracy.
Do webhook events replace the need to call the API?
No. Webhooks push real-time status changes, while the signed-JSON API remains the source of truth for backfilling history, running reconciliation jobs, or pulling full evidence bundles on demand.
Ready to see the event catalog against your own integration plan? Contact areturnz to walk through webhook setup for your tenant.
Related reading: Choosing a returns node location: facility footprint and regional coverage economics
Proof on every return
Photos, an AI condition grade, and a full custody chain, attached to every parcel and available via the API.
