What are webhooks?
Webhooks are a simple way for Swap to automatically push order data to your system in real time - particularly duty and tax data for international orders that use Swap Global (not Clear. For setup solutions that solve for Clear, please return to our WMS/3PL integration section).
Think webhooks like subscribing to updates - every time an order is placed, we will send you the data in your chosen format. You can choose to receive the full canonical payload or use a custom schema.
How it works:
You provide a secure URL
When a Swap order is created, we send the order data to that URL
You receive the data instantly via an HTTP POST
Benefits of using webhooks (vs API call/Shopify JSON notes):
Swap handles delivery, retries, and infrastructure
Setup typically takes minutes
No deep API knowledge required
No polling or manual requests on your behalf
What data do Swap webhooks send?
Every webhook delivers a complete Swap order payload, either in Swap’s canonical format or transformed into a partner-specific schema.
Webhooks always send the full order payload, not partial updates, so downstream systems don’t need to reconcile multiple events.
The payload includes all data required for customs, compliance and landed-cost workflows:
Order summary
Line items
Tax and duty amounts
HS codes and country of origin
Importer, exporter, and consignee details
Order type (e.g. B2C, B2B2C)
Canonical payload vs custom schema
You have two options for how you would like to receive the webhook data:
Option 1: Receive the full Swap payload (no schema) - default option
If you’re happy to work with Swap’s canonical payload as-is:
We send the full Swap order object unchanged
You parse and map the fields you need internally
This works well if you:
Want maximum flexibility
Have the resources on your side to enforce mapping logic
Prefer to control transformation
Option 2: Receive data in your required format (partner schema)
If you require a specific JSON structure, Swap can automatically transform the canonical payload into your required schema before delivery.
In this case:
You provide a schema that defines your required format
Swap applies that schema when sending webhook events
You receive data already shaped to your expectations
This works well if you:
Have rigid ingestion requirements
Don’t have the resources on your side to enforce mapping logic
Integrate directly into legacy systems
Want consistency across all inbound data
Important note: schemas can be added later
If you prefer, you can start using webhooks with the canonical payload (no specific schema) then add your partner-specific schema later if requirements change.
When a schema is added:
The webhook configuration stays the same
New Swap orders are delivered using the new schema
No reintegration is required
This allows you to start quickly and evolve over time.
What don’t webhooks do?
Webhooks are focused on delivery, not business logic.
You are still responsible for:
Mapping fields into your internal models
Applying conditional logic (e.g. order type filtering)
Routing data to downstream systems - ie. using the productprice data field from the webhook to call the carrier, so that the data appears correctly on the commercial invoice
Combining Swap data with your own sources
Webhooks remove the integration complexity, not the data usage logic.
Can I replay or fetch old events?
You can choose what webhook data you store and how long for.
For example, you could choose to retain webhook payloads in your own database for a timeframe of 90 days, so that you can
Fetch historical orders from within this timeframe
Re-check a specific order
Query data on demand
(If you need to do any of the above with orders that fall outside of your chosen window, you can use the Swap API.)
Summary
Webhooks push Swap order data to you automatically
Setup is fast and low-effort
You can receive the full canonical payload or use a custom schema
A custom schema can be added later if required
Webhooks and APIs are complementary
If you’re unsure which option is best, starting with the canonical payload is usually the fastest path. If you’d like to get started with webhooks, please contact your onboarding/account manager, and they will help you get set up.