Webhooks Reference

Webhooks allow external systems to receive real-time HTTP notifications when events occur in ReturnMate. Use webhooks to trigger workflows, sync data, or build custom integrations.

What Are Webhooks?

Webhooks are HTTP callbacks that notify your systems when something happens:

[ReturnMate Event] → [HTTP POST to your endpoint] → [Your system processes]

Available Webhook Events

RMA Events

Shipment Events

Warranty Events

Financial Events

Inspection Events

Setting Up Webhooks

📷

Webhook Configuration

(Screenshot placeholder)

Webhook Payload

Payload Structure

{
  "event": "rma.created",
  "timestamp": "2024-12-31T14:30:00Z",
  "data": {
    "rmaId": "rma_abc123",
    "rmaNumber": "RMA-2024-001234",
    "status": "pending",
    "customer": {
      "email": "customer@example.com",
      "name": "John Smith"
    },
    "items": [...]
  }
}

Headers

Webhooks include these headers:

Webhook Security

Signature Verification

Verify webhook authenticity using the signature:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Best Practices

• Always verify signatures
• Use HTTPS endpoints only
• Validate event timestamps
• Handle duplicates (use delivery ID)
• Respond quickly (within 30 seconds)

Reliability

Retry Policy

Failed deliveries are retried:

After 6 failed attempts, the webhook is marked as failed.

Handling Failures

When webhooks fail:

1. Check your endpoint is accessible
2. Review error logs
3. Fix issues and re-enable
4. Request replay if needed

Idempotency

Handle potential duplicate deliveries:

1. Store the delivery ID
2. Check before processing
3. Skip if already processed

Webhook Logs

Viewing Logs

1. Go to Settings → Webhooks
2. Click on a webhook
3. View Delivery Log

Log Information

Each delivery shows:

• Timestamp
• Event type
• Response status
• Response time
• Payload (expandable)
• Error details (if failed)

Duplicate Handling

Why Duplicates Occur

Webhooks may be sent multiple times due to:

• Network issues
• Retry after timeout
• System recovery

Prevention Strategy

Implement idempotency in your handler:

async function handleWebhook(event) {
  const deliveryId = event.headers['x-returnmate-delivery-id'];

  // Check if already processed
  if (await isProcessed(deliveryId)) {
    return { status: 200, message: 'Already processed' };
  }

  // Process the event
  await processEvent(event.body);

  // Mark as processed
  await markProcessed(deliveryId);

  return { status: 200 };
}

Troubleshooting

Common Issues

Testing Webhooks

Use tools like:

• ngrok for local testing
• Webhook.site for quick tests
• ReturnMate's test feature

Shopify Webhook Guidance

Handling Shopify Webhooks

ReturnMate also receives webhooks from Shopify. For your own integrations:

• Order Updates - Sync order changes
• Product Updates - Keep products current
• App Uninstalled - Handle disconnection

Reliability with Shopify

Shopify webhooks can also have reliability issues:

• Implement the same idempotency patterns
• Log all received webhooks
• Handle out-of-order delivery

Related Articles

• Integrations Overview
• Monitoring & Logs
• Duplicate Webhooks