For up-to-date payload schemas, JWT verification details, and configuration options, visit our API docs.
Webhooks are a way for applications to communicate automatically with each other. When an event occurs in Swap (for example, a return is processed), a webhook sends real-time data to another system via an HTTP callback. This process is automated, so no manual action is needed to update information across systems.
This article is for users of Returns V2. For the Returns V1 version, see Webhook for Return Data.
Events
Swap webhooks are available for the following events:
Return created – triggered when a new return is created in the portal.
Return processed – triggered when the RMA is finalised and processed in your dashboard.
Versions
There are two versions of webhook payloads:
Version 1 – the original schema (still supported).
Version 2 – the current schema, which adds fields such as RMA number, shipping address, and split shipment support. This is the recommended version for new integrations.
Authentication
Authentication is handled with JSON Web Tokens (JWT). Swap includes the signed JWT in the request body. Verify it using your previously shared secret key. The JWT includes an expiry timestamp (exp) to prevent replay attacks.
How to configure a webhook
Go to the Integrations screen in your dashboard.
Click New webhook.
Fill out the required fields (all required unless stated otherwise):
Webhook Name – Give your webhook an identifying name.
Description – Add a description for your convenience (for example: the objective of the webhook).
URL – The endpoint where the webhook should send data.
Event – Choose the event that will trigger the webhook.
After creating the first webhook, you will be shown a secret key to enable authentication. Copy it and store it securely. It cannot be revealed again.
Rotating your webhook secret key
You can rotate your webhook secret key directly from the Swap dashboard, without contacting support.
Go to Returns → Integrations in the Swap dashboard.
In the Webhook secret key panel, click the refresh icon.
Rotating deactivates the old key immediately and issues a new one, so update your endpoint's JWT verification with the new key before rotating to avoid dropped deliveries.