Optoro Webhooks

generated: '2026-08-26'
method: searched
source: https://developer.optoro.com/content/webhooks
docs:
- https://developer.optoro.com/content/webhooks
- https://developer.optoro.com/content/rx_integration_guide
asyncapi_published: false
asyncapi_note: >-
  Optoro publishes NO AsyncAPI document. It documents its event surface as OpenAPI POST operations against an
  endpoint the CUSTOMER hosts — nine of the seventeen published definitions describe Optoro-to-customer
  messages rather than customer-to-Optoro calls, with servers[] pointing at developer.optoro.com as a
  documentation placeholder because the real target URL is supplied by the integrator. No AsyncAPI file was
  fabricated here; this artifact is the webhook catalog Optoro actually publishes.
delivery:
  guarantee: at-least-once
  ordering: not guaranteed — delivery is parallelized; most messages carry a timestamp for reordering
  duplicates: expected — "your webhook must be able to handle them"
  latency: asynchronous, not real time
  transport: HTTPS POST, TLS 1.2 minimum, certificate must be signed by a globally trusted CA with intermediates installed
  content_type: application/json
  method: POST
  success_criteria: any 2xx (200 OK recommended)
  retry:
    window: up to 32 hours
    strategy: exponential backoff
    retriable_status_codes: [500, 502, 503, 504]
    also_retried: connection timeouts
    reauth_on: 401 — Optoro re-authenticates and retries
    do_not_return: 400 / 422 — "quietly ignore the message and respond with a 200 OK"
  retention: 30 days; replay outside the 32-hour window requires Optoro Client Success
  configuration: >-
    Webhooks are configured by Optoro's Client Success team, not self-serve. Required from the integrator:
    the list of webhooks to enable, a URL for each, and authentication details.
  authentication_supported:
  - Basic Auth
  - OAuth 2
  - AWS SigV4
  - API key in an HTTP header
  credential_handling: secrets sent to Client Success as encrypted files and stored encrypted
surface_kinds:
- kind: webhook
  definition: Called when an event occurs in Optoro's system ("telling"). Response only acknowledges receipt; Optoro does not act on the body.
- kind: customer-endpoint
  definition: Called when Optoro needs information ("asking"). The response body influences Optoro's behaviour.
webhooks:
- name: RMAs
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: rmas
  spec: openapi/optoro-rmas-openapi.yml
  version: 5.0.0
  version_header: 'X-Optiturn-Api-Version: 3'
  url: https://developer.optoro.com/openapi/rmas/openapi
  events:
  - shopper initiates a return
  - carrier tracking details provided
  - carrier receives and scans the return
  - shopper drops off the return, or a pick-up partner collects it
  - item received and ready for refund (Returns Management customers)
  - retailer posts refund details in the Refunds object of the Returns Portal Orders API
- name: Disposition Update
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: dispositions
  spec: openapi/optoro-disposition-update-openapi.yml
  url: https://developer.optoro.com/openapi/disposition_update/openapi
  events:
  - a unit's disposition or condition changes in the warehouse or store
- name: Final Disposition
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: final_dispositions
  spec: openapi/optoro-final-disposition-openapi.yml
  url: https://developer.optoro.com/openapi/final_disposition/openapi
  events:
  - a unit reaches its terminal disposition
- name: Outbound ASN
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: outbound_asns
  spec: openapi/optoro-outbound-asn-openapi.yml
  url: https://developer.optoro.com/openapi/outbound_asn/openapi
  events:
  - outbound shipment (including stock transfers) leaves an Optoro facility
- name: Drop Shipment Confirmation
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: drop_shipment_confirmation
  spec: openapi/optoro-drop-ship-webhooks-openapi.yml
  url: https://developer.optoro.com/openapi/drop_ship/webhooks/openapi
  events:
  - a drop shipment is confirmed
- name: Drop Shipment Cancellation
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: drop_shipment_cancellation
  spec: openapi/optoro-drop-ship-webhooks-openapi.yml
  url: https://developer.optoro.com/openapi/drop_ship/webhooks/openapi
  events:
  - a drop shipment is cancelled in full
- name: Drop Shipment Partial Cancellation
  kind: webhook
  direction: optoro-to-customer
  method: POST
  operation_id: drop_shipment_partial_cancellation
  spec: openapi/optoro-drop-ship-webhooks-openapi.yml
  url: https://developer.optoro.com/openapi/drop_ship/webhooks/openapi
  events:
  - part of a drop shipment is cancelled
customer_endpoints:
- name: Exchange Orders
  kind: customer-endpoint
  direction: optoro-to-customer
  method: POST
  operation_id: exchange_orders
  spec: openapi/optoro-exchange-orders-openapi.yml
  version_header: 'X-Optiturn-Api-Version: 1 | 2'
  url: https://developer.optoro.com/openapi/exchange_orders/openapi
  idempotency_key: original_order_id
  contract: >-
    "Your endpoint should handle all tax and shipping calculations. The endpoint should be idempotent, using
    original_order_id as the key. Only one exchange order can be placed against an original_order_id."
  events:
  - shopper confirms an exchange
  - shopper selects a gift-card refund
  - instant exchange / instant gift card
- name: Exchange Variants
  kind: customer-endpoint
  direction: optoro-to-customer
  method: GET
  operation_id: variants
  spec: openapi/optoro-variants-openapi.yml
  version_header: 'X-Optiturn-Api-Version: 1'
  url: https://developer.optoro.com/openapi/variants/openapi
  contract: Optoro GETs /sku/{parent_sku}/variants from the retailer to offer even-exchange options to the shopper.
- name: Forward Orders
  kind: customer-endpoint
  direction: optoro-to-customer
  method: POST
  spec: openapi/optoro-forward-orders-openapi.yml
  url: https://developer.optoro.com/openapi/forward_orders/openapi
  deprecated: true
counts:
  webhooks: 7
  customer_endpoints: 3
  total_event_operations: 10