Handling Relay Point Selection

Overview

When a user selects a relay point in the map, you can receive that data via a webhook callback. This allows your application to automatically save the selection and update the delivery address.

Setting Up Callbacks

Step 1: Prepare Your Endpoint

Create an HTTP endpoint that accepts POST requests:

POST https://yourapplication.com/api/relay-point-selected

Step 2: Include Callback URL

Add the callbackUrl parameter to your iframe URL:

<iframe
  src="https://relay-points-map.wing.eu?channelId=9eca5686-faea-4d9f-8de0-4a0221814644&callbackUrl=https%3A%2F%2Fyourapplication.com%2Fapi%2Frelay-point-selected"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Step 3: Process the Callback

Implement your callback endpoint to handle the relay point data.

Callback Payload

When a relay point is selected, we send a POST request to your callback URL with the following JSON payload:

{
  "relayPointId": "string",
  "service": "MONDIAL_RELAY",
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "zip": "string",
    "city": "string",
    "countryCode": "string"
  },
  "coordinates": {
    "latitude": "number",
    "longitude": "number"
  },
  "openingHours": [
    {
      "day": "string",
      "open": "string",
      "close": "string"
    }
  ]
}

Payload Fields

Field	Type	Description	Example
relayPointId	string	Unique identifier for the relay point	XYZ123
service	string	The carrier service	MONDIAL_RELAY
name	string	Relay point name	Carrefour Express - Paris 15
address.line1	string	Street address	123 rue de la Paix
address.line2	string	Additional address info	Bâtiment C
address.zip	string	Postal code	75015
address.city	string	City name	Paris
address.countryCode	string	ISO country code	FR
coordinates.latitude	number	GPS latitude	48.8566
coordinates.longitude	number	GPS longitude	2.3522
openingHours[].day	string	Day of week	Monday
openingHours[].open	string	Opening time	09:00
openingHours[].close	string	Closing time	20:00

Implementation Examples

Callback Implementation Examples

Examples showing how to handle relay point selection callbacks in different programming languages and frameworks

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

app.use(express.json());

app.post('/api/relay-point-selected', async (req, res) => {
try {
  const relayPoint = req.body;

  // Validate payload
  if (!relayPoint.relayPointId || !relayPoint.address?.zip) {
    return res.status(400).json({
      error: 'Invalid payload'
    });
  }

  // Save to database
  await saveRelayPointSelection(relayPoint);

  // Log the selection
  console.log('Relay point selected:', {
    id: relayPoint.relayPointId,
    service: relayPoint.service,
    name: relayPoint.name
  });

  return res.status(200).json({
    success: true,
    message: 'Relay point selection saved'
  });
} catch (error) {
  console.error('Error processing callback:', error);
  return res.status(500).json({
    error: 'Internal server error'
  });
}
});

async function saveRelayPointSelection(relayPoint) {
// Database insert logic here
}

Response Requirements

Your callback endpoint must respond with:

• Status Code: 200 (OK) or any 2xx success code
• Content-Type: application/json (recommended)
• Response Time: Within 30 seconds

Valid Response Example

{
  "success": true,
  "message": "Relay point selection saved successfully"
}

Error Handling

Callback Failures

If your endpoint returns an error (non-2xx status code), the relay point map will:

1. Display an error message to the user
2. Allow the user to retry the selection

Troubleshooting

Callbacks Not Being Received

• Verify the callbackUrl is correct and URL-encoded
• Ensure your endpoint is publicly accessible
• Check your firewall/security rules
• Monitor server logs for incoming requests
• Verify your endpoint accepts POST requests

Invalid Payload

• Log the entire request body
• Validate each field before processing
• Check for missing or null fields
• Ensure your JSON parsing is correct

Server Errors (5xx responses)

• Check your application logs
• Verify database connections
• Ensure all dependencies are available
• Test the endpoint with curl:

curl -X POST https://yourapplication.com/api/relay-point-selected \
  -H "Content-Type: application/json" \
  -d '{"relayPointId":"123","service":"MONDIAL_RELAY"}'

Next Steps

• Review Iframe Integration for embedding the map
• Explore Authentication & Parameters for advanced options