Webhooks & REST API + ReturnMate
ReturnMate exposes a REST API for third-party systems (POS, ERP, TradeMate, custom tooling) to create RMAs, poll for status, and subscribe to webhook events. Clean authentication, stable endpoints, HMAC-signed webhooks for verifiability.
What the integration does.
- X-Api-Key authentication with per-client provisioning
- REST endpoints for trade returns, offline repairs, status queries
- HMAC-SHA256 signed webhooks for lifecycle events
- Pagination + filter query params on list endpoints
- Rate-limited per client (30 req/min on creation endpoints)
- No-retry webhook delivery with idempotent event IDs
How merchants use it.
POS-initiated offline repair
Your POS creates a repair intake when a customer drops off an item at the counter. Calls POST /external/v1/offline-repairs with serial, fault description, and customer email — ReturnMate creates the RMA in COUNTER_SWAPPED state and streams status back via webhooks.
ERP-driven trade returns
Your ERP calls POST /external/v1/trade-returns when a B2B customer requests a credit. ReturnMate provisions the RMA, generates any required label, and pushes trade_return.credit_requested back to the ERP when a credit is approved.
Event-driven downstream sync
Subscribe to all RMA lifecycle events to drive your own automations — Slack notifications when an RMA hits a breach, Google Sheets log of resolved RMAs, custom reporting pipelines, etc.
Connect Webhooks & REST API in minutes.
- 1
Generate an API key
Settings → External API → Generate API Key. Name the integration, paste a webhook URL if you want push events, and save. The API key and webhook secret display once — copy them both immediately.
- 2
Verify webhook signatures
On every incoming webhook, compute HMAC-SHA256(body, webhookSecret) in hex and compare constant-time against the X-Webhook-Signature header. Reject if unsigned or mismatched.
- 3
Call the endpoints
Send requests with X-Api-Key header. See documentation in the admin (Settings → External API) for full endpoint reference. Rate limits apply per-client, not per-shop.
Questions about Webhooks & REST API.
Are webhooks retried?
No. Delivery is fire-and-forget. Your endpoint should be idempotent on event ID and you should reconcile missed events by polling the list endpoint (GET /external/v1/trade-returns, etc.) on a schedule.
What's the rate limit?
30 requests per minute per API client on creation endpoints. Read endpoints are unthrottled for now. If you need higher limits, contact us — Enterprise plans include elevated limits.
Can I rotate an API key?
Yes. Revoke the old key (Settings → External API → Revoke) and generate a new one. There's no downtime-free rotation — new requests must use the new key from the moment you revoke the old one. Webhook secrets rotate similarly.
Ready to connect Webhooks & REST API?
14-day free trial. No credit card required. Billed through Shopify.