Webhook Events

Event types

M2M sends webhooks for the following events:

Event	Description
`link.created`	A magic link was created
`link.opened`	User opened a magic link
`user.data_request`	M2M needs additional user data for verification
`operation.created`	A money transfer operation was created
`operation.cancelled`	A money transfer operation was cancelled

link.created

Sent when a magic link is created via the API. Use this to confirm link creation asynchronously and track the beginning of the link lifecycle.

Payload

{
  "event": "link.created",
  "timestamp": "2026-01-26T14:30:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "url": "https://send.m2m.leapfinancial.com/link_acme_a1b2c3d4e5f6",
    "status": "created",
    "expiresAt": "2026-01-27T14:30:00.000Z",
    "createdAt": "2026-01-26T14:30:00.000Z"
  }
}

string

required

Always link.created.

string

required

ISO 8601 timestamp when the webhook was generated.

object

required

Event payload.

Show data properties

string

required

The magic link identifier.

string

required

Your user identifier.

string

required

The full magic link URL to share with the user.

string

required

Link status. Always created for this event.

string

required

ISO 8601 timestamp when the magic link expires.

string

required

ISO 8601 timestamp when the link was created.

Example handler

Node.js

app.post('/webhooks/m2m', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'link.created') {
    console.log(`Link ${data.linkId} created for user ${data.referenceId}`);
    
    // Store the link in your system
    await db.links.create({
      linkId: data.linkId,
      referenceId: data.referenceId,
      url: data.url,
      expiresAt: data.expiresAt,
      createdAt: data.createdAt
    });
  }
  
  res.status(200).send('OK');
});

link.opened

Sent when a user opens a magic link for the first time. Use this to track engagement and prepare for potential data requests.

Payload

{
  "event": "link.opened",
  "timestamp": "2026-01-26T14:30:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "openedAt": "2026-01-26T14:30:00.000Z",
    "deviceInfo": {
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...",
      "platform": "iOS",
      "language": "en-US"
    }
  }
}

string

required

Always link.opened.

string

required

ISO 8601 timestamp when the webhook was generated.

object

required

Event payload.

Show data properties

string

required

The magic link identifier.

string

required

Your user identifier.

string

required

ISO 8601 timestamp when the user opened the link.

object

Information about the user’s device.

Show deviceInfo properties

string

Browser user agent string.

string

Detected platform (iOS, Android, Windows, macOS, Linux, etc.).

string

Browser language preference.

Example handler

Node.js

app.post('/webhooks/m2m', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'link.opened') {
    console.log(`User ${data.referenceId} opened link ${data.linkId}`);
    
    // Update your records
    await db.users.update({
      where: { referenceId: data.referenceId },
      data: { lastLinkOpenedAt: data.openedAt }
    });
    
    // Prepare for potential data request
    await prepareUserDataForM2M(data.referenceId);
  }
  
  res.status(200).send('OK');
});

user.data_request

Sent when M2M needs additional user data to complete identity verification (CIP). This happens when the user data provided during link creation is incomplete.

This webhook gives you an opportunity to provide user data before M2M asks the user directly. Responding quickly improves user experience.

Payload

{
  "event": "user.data_request",
  "timestamp": "2026-01-26T14:30:00.000Z",
  "data": {
    "dataRequestId": "dr_acme_x9y8z7w6v5u4",
    "referenceId": "user_12345",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "requiredFields": [
      "name.secondName",
      "name.secondLastName",
      "idNumber",
      "idType",
      "dob"
    ],
    "replyEndpoint": "https://m2m-backend-qa.up.railway.app/partner/data-requests/dr_acme_x9y8z7w6v5u4",
    "expiresAt": "2026-01-26T15:30:00.000Z"
  }
}

string

required

Always user.data_request.

string

required

ISO 8601 timestamp when the webhook was generated.

object

required

Event payload.

Show data properties

string

required

Unique identifier for this data request. Use this when responding.

string

required

Your user identifier.

string

required

The magic link identifier.

array

required

List of fields M2M needs. Possible values:

name.firstName
name.secondName
name.lastName
name.secondLastName
idNumber
idType
dob

string

required

Full URL to send the user data to. Make a PUT request to this URL.

string

required

ISO 8601 timestamp when this data request expires. Same as link expiration.

Responding to data requests

When you receive this webhook, you can provide the missing data by making a PUT request to the replyEndpoint:

cURL

curl -X PUT https://m2m-backend-qa.up.railway.app/partner/data-requests/dr_acme_x9y8z7w6v5u4 \
  -H "X-API-Key: m2m_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "user_12345",
    "userData": {
      "name": {
        "secondName": "Carlos",
        "secondLastName": "Lopez"
      },
      "idNumber": "GALO900515HDFRPN09",
      "idType": "CURP",
      "dob": "1990-05-15"
    }
  }'

You only need to provide the fields listed in requiredFields. Any additional fields you provide will be stored but aren’t required.

Response to your PUT request

{
  "success": true,
  "data": {
    "dataRequestId": "dr_acme_x9y8z7w6v5u4",
    "status": "fulfilled",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "fulfilledAt": "2026-01-26T14:35:00.000Z",
    "message": "User data received and merged successfully"
  }
}

Example handler

Node.js

app.post('/webhooks/m2m', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'user.data_request') {
    // Acknowledge immediately
    res.status(200).send('OK');
    
    // Fetch user data from your system
    const user = await db.users.findUnique({
      where: { referenceId: data.referenceId }
    });
    
    if (!user) {
      console.log(`User ${data.referenceId} not found`);
      return;
    }
    
    // Build the response with requested fields
    const userData = {};
    
    if (data.requiredFields.includes('name.secondName')) {
      userData.name = userData.name || {};
      userData.name.secondName = user.middleName;
    }
    
    if (data.requiredFields.includes('idNumber')) {
      userData.idNumber = user.governmentId;
    }
    
    if (data.requiredFields.includes('dob')) {
      userData.dob = user.dateOfBirth;
    }
    
    // Send the data to M2M
    await fetch(data.replyEndpoint, {
      method: 'PUT',
      headers: {
        'X-API-Key': process.env.M2M_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        referenceId: data.referenceId,
        userData
      })
    });
    
    return;
  }
  
  res.status(200).send('OK');
});

What happens if you don’t respond?

If you don’t respond to the data request (or can’t provide the data), M2M will prompt the user to enter the missing information directly in the widget. This increases friction but ensures the transaction can still complete. See Data Requests for more details on this flow.

operation.created

Sent when a user completes a money transfer operation through the widget. Use this to record transactions in your system and trigger downstream processes.

Payload

{
  "event": "operation.created",
  "timestamp": "2026-01-26T14:30:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "userId": "usr_x9y8z7w6v5u4",
    "status": "created",
    "funding": {
      "method": "card",
      "last4": "4242",
      "bankName": "visa"
    },
    "payout": {
      "method": "bank_account"
    },
    "amount": {
      "send": 100.00,
      "receive": 1850.50,
      "rate": 18.505,
      "fee": 3.99,
      "currency": {
        "send": "USD",
        "receive": "MXN"
      }
    },
    "createdAt": "2026-01-26T14:30:00.000Z"
  }
}

string

required

Always operation.created.

string

required

ISO 8601 timestamp when the webhook was generated.

object

required

Event payload.

Show data properties

string

required

Unique identifier for the operation. Format: op_{12chars}.

string

required

The magic link identifier.

string

required

Your user identifier.

string

required

M2M’s internal user identifier.

string

required

Operation status. Initially created.

object

required

Funding source details.

Show funding properties

string

required

Funding method used (card, bank_account, etc.).

string

Last 4 digits (for card payments).

string

Card brand or bank name.

object

required

Payout destination details.

Show payout properties

string

required

Payout method (bank_account, card, cash).

object

required

Transaction amounts.

Show amount properties

number

required

Amount sent in source currency.

number

required

Amount received in destination currency.

number

required

Exchange rate applied.

number

required

Transaction fee.

object

required

Currency codes.

Show currency properties

string

required

Source currency (e.g., USD).

string

required

Destination currency (e.g., MXN).

string

required

ISO 8601 timestamp when the operation was created.

Example handler

Node.js

app.post('/webhooks/m2m', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'operation.created') {
    console.log(`Operation ${data.operationId} created for user ${data.referenceId}`);
    
    // Record the operation in your system
    await db.operations.create({
      operationId: data.operationId,
      referenceId: data.referenceId,
      sendAmount: data.amount.send,
      receiveAmount: data.amount.receive,
      fee: data.amount.fee,
      status: data.status,
      createdAt: data.createdAt
    });
    
    // Notify your team or trigger downstream processes
    await notifyTeam('New M2M operation', data);
  }
  
  res.status(200).send('OK');
});

operation.cancelled

Sent when a user cancels a money transfer operation from the widget. Use this to update your records, release any held resources, and keep your system in sync.

If you’ve already begun processing the operation on your side (e.g., provisional balance holds), make sure your cancellation handler reverses that state.

Payload

{
  "event": "operation.cancelled",
  "timestamp": "2026-01-26T14:35:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "userId": "usr_x9y8z7w6v5u4",
    "status": "cancelled",
    "cancellationReason": "user_requested",
    "cancelledAt": "2026-01-26T14:35:00.000Z"
  }
}

string

required

Always operation.cancelled.

string

required

ISO 8601 timestamp when the webhook was generated.

object

required

Event payload.

Show data properties

string

required

Unique identifier for the operation. Format: op_{12chars}.

string

required

The magic link identifier.

string

required

Your user identifier.

string

required

M2M’s internal user identifier.

string

required

Operation status. Always cancelled for this event.

string

required

Reason the operation was cancelled (e.g., user_requested).

string

required

ISO 8601 timestamp when the operation was cancelled.

Example handler

Node.js

app.post('/webhooks/m2m', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'operation.cancelled') {
    console.log(`Operation ${data.operationId} cancelled for user ${data.referenceId}`);
    
    // Update the operation status in your system
    await db.operations.update({
      where: { operationId: data.operationId },
      data: {
        status: 'cancelled',
        cancellationReason: data.cancellationReason,
        cancelledAt: data.cancelledAt
      }
    });
    
    // Release any held resources
    await releaseHeldFunds(data.operationId);
  }
  
  res.status(200).send('OK');
});

Handling webhooks

Complete example

Here’s a complete webhook handler that processes all event types:

Node.js

const express = require('express');
const crypto = require('crypto');

const app = express();

// Use raw body for signature verification
app.use('/webhooks/m2m', express.raw({ type: 'application/json' }));

app.post('/webhooks/m2m', async (req, res) => {
  // Verify signature
  const signature = req.headers['x-m2m-signature'];
  const timestamp = req.headers['x-m2m-timestamp'];
  
  if (!verifySignature(req.body.toString(), signature, timestamp)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Parse the body
  const { event, data } = JSON.parse(req.body);
  
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  try {
    switch (event) {
      case 'link.created':
        await handleLinkCreated(data);
        break;
      case 'link.opened':
        await handleLinkOpened(data);
        break;
      case 'user.data_request':
        await handleDataRequest(data);
        break;
      case 'operation.created':
        await handleOperationCreated(data);
        break;
      case 'operation.cancelled':
        await handleOperationCancelled(data);
        break;
      default:
        console.log(`Unknown event: ${event}`);
    }
  } catch (error) {
    console.error(`Error processing ${event}:`, error);
    // Don't throw - we already responded 200
  }
});

function verifySignature(payload, signature, timestamp) {
  const secret = process.env.M2M_WEBHOOK_SECRET;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', '')),
    Buffer.from(expected)
  );
}

async function handleLinkCreated(data) {
  console.log(`Link created: ${data.linkId} for user ${data.referenceId}`);
  // Your logic here - store the link, send it to the user, etc.
}

async function handleLinkOpened(data) {
  console.log(`Link opened: ${data.linkId} by user ${data.referenceId}`);
  // Your logic here
}

async function handleDataRequest(data) {
  console.log(`Data request: ${data.dataRequestId} for user ${data.referenceId}`);
  // Your logic here - fetch and send user data
}

async function handleOperationCreated(data) {
  console.log(`Operation created: ${data.operationId} for user ${data.referenceId}`);
  // Your logic here - record the operation, notify team, etc.
}

async function handleOperationCancelled(data) {
  console.log(`Operation cancelled: ${data.operationId} for user ${data.referenceId}`);
  // Your logic here - update status, release held resources, etc.
}

app.listen(3000);

Getting Started

Integration

Webhooks

Event types

link.created

Payload

Example handler

link.opened

Payload

Example handler

user.data_request

Payload

Responding to data requests

Response to your PUT request

Example handler

What happens if you don’t respond?

operation.created

Payload

Example handler

operation.cancelled

Payload

Example handler

Handling webhooks

Complete example

Next steps

Webhook Security

Data Requests

​Event types

​link.created

​Payload

​Example handler

​link.opened

​Payload

​Example handler

​user.data_request

​Payload

​Responding to data requests

​Response to your PUT request

​Example handler

​What happens if you don’t respond?

​operation.created

​Payload

​Example handler

​operation.cancelled

​Payload

​Example handler

​Handling webhooks

​Complete example

​Next steps

Webhook Security

Data Requests

Event types

link.created

Payload

Example handler

link.opened

Payload

Example handler

user.data_request

Payload

Responding to data requests

Response to your PUT request

Example handler

What happens if you don’t respond?

operation.created

Payload

Example handler

operation.cancelled

Payload

Example handler

Handling webhooks

Complete example

Next steps