Returns webhooks reference (Returns V2)

Webhooks send Swap return data to your systems when a return is created or processed. This article covers events, payload versions, authentication, retries and setup.

3 min readUpdated Oct 29, 2026

Webhooks send return data from Swap to your own systems as soon as a return is created or processed. This article covers the events, payload versions, authentication, delivery retries and how to set up a webhook. For payload schemas and example payloads, see the webhooks documentation.

Events

Event

Sent when

Return created (returnCreated)

A customer submits a return request

Return processed (returnProcessed)

A return is processed, for example a refund is issued or an exchange order is created

An advanced rule can also call a webhook when a return matches its conditions. Each call is recorded in the RMA's history log. See Understanding advanced rules (Returns V2).

Payload versions

You choose a payload version for each webhook. Use V2 for new integrations.

V2 adds the following to the payload:

  • return_shipments: one object per shipment, including split shipments
  • exchange_products: the exchange items
  • result_type: where the refund or credit goes, for example store-credit or refund-money
  • total_store_credit_value_customer_currency: the store credit value
  • portal_quick_link: a quick-login link to the customer's return in the portal

V2 also replaces V1's status and shipping_status with return_status and delivery_status.

Authentication

Each delivery includes a signed JSON Web Token (JWT) in the jwt field of the request body. Verify its signature with your webhook secret key before you process the payload.

  • The JWT is signed with HS256.
  • It expires 5 minutes after it is issued.
  • Every delivery attempt carries a new JWT with its own nonce.

Retries

Swap retries a failed delivery up to three times, after 1, 2 and 5 seconds. A delivery fails if your endpoint returns any status other than 2xx, doesn't respond within 5 seconds, or can't be reached. Return a 2xx response promptly to avoid unnecessary retries.

Test deliveries carry the header X-Swap-Test-Webhook: true, so you can tell them apart from real events.

How to set up a webhook

  1. Go to Returns → Integrations in the Swap dashboard.
  2. Click New webhook.
  3. Fill in the fields:
    • Webhook Name: a name to identify the webhook.
    • Description: a note for your own reference, for example what the webhook is for.
    • URL: the endpoint Swap sends data to.
    • Event: the event that triggers the webhook.
    • The payload version, V1 or V2.
  4. After you create your first webhook, Swap shows your webhook secret key. Copy it and store it securely. It isn't shown again.

How to rotate your webhook secret key

  1. Go to Returns → Integrations in the Swap dashboard.
  2. In the Webhook secret key panel, click the refresh icon.

Rotating deactivates the old key immediately. Update your endpoint's JWT verification with the new key before you rotate, or deliveries will fail verification.