Webhooks

Overview

Webhooks allow your application to receive real-time notifications about events that occur in your MigrateClouds account. When an event occurs, we'll send an HTTP POST request to the URL you've configured, containing information about the event.

Setting Up Webhooks

You can configure webhooks in your MigrateClouds dashboard under Settings → Webhooks. You'll need to provide:

• A name for your webhook (for your reference)
• The destination URL where we'll send the webhook payload
• The events you want to subscribe to
• An optional secret key for verifying webhook signatures

Available Events

MigrateClouds can send webhooks for the following events:

Webhook Payload

Webhook payloads are sent as JSON in the body of the POST request. Here's an example of a webhook payload for a transfer.completed event:

{
  "id": "evt_123456789",
  "type": "transfer.completed",
  "created_at": "2023-04-15T12:34:56Z",
  "data": {
    "transfer_id": "trf_987654321",
    "source": {
      "service": "google_drive",
      "path": "/Documents/report.pdf"
    },
    "destination": {
      "service": "dropbox",
      "path": "/Backup/report.pdf"
    },
    "file_size": 1048576,
    "duration_ms": 2345
  }
}

Verifying Webhooks

To ensure that webhook requests are coming from MigrateClouds and not a third party, we include a signature in the X-MigrateClouds-Signature header of each request. You should verify this signature before processing the webhook.

The signature is created by signing the request body with your webhook secret using HMAC-SHA256.

const crypto = require('crypto');

// Your webhook secret from the MigrateClouds dashboard
const secret = 'whsec_...';

// Express route handler
app.post('/webhooks/migrateclouds', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-migrateclouds-signature'];
  
  // Create the expected signature
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(req.body).digest('hex');
  
  // Compare signatures
  if (signature === expectedSignature) {
    // Signature is valid, process the webhook
    const payload = JSON.parse(req.body);
    console.log('Received valid webhook', payload);
    res.status(200).send('Webhook received');
  } else {
    // Signature is invalid
    console.error('Invalid webhook signature');
    res.status(401).send('Invalid signature');
  }
});

Best Practices

• Always verify the webhook signature to ensure the request is from MigrateClouds
• Respond to webhook requests quickly (within 5 seconds) to avoid timeouts
• Implement idempotency in your webhook handlers to handle potential duplicate events
• Set up monitoring for your webhook endpoints to detect and respond to failures
• Use a webhook testing tool like Webhook.site during development

Troubleshooting