Webhook Integration

Welcome to the Developer API. Our webhooks allow your system to communicate directly with our platform in real-time. This guide details how to securely authenticate your requests and structure your payloads for order creation and tracking updates.

Webhook Authentication

Strict Requirement: Every request sent to our platform must include the security headers below. Requests missing these headers will be rejected with a 401 Unauthorized status.

Please include the following headers in your HTTP POST requests:

Header Name	Description
X-Webhook-ClientId	Unique identifier for your shop/application.
X-Webhook-Signature	HMAC-SHA256 hash of the JSON payload signed with your Secret Key.

Secret Key Management

Generation: The secret key is generated in your LeadDone Account under Intégrations > Webhook.
Storage: Never expose this key in client-side code. Store it securely in your server's environment variables (e.g., .env file) or a secrets manager (e.g., AWS Secrets Manager, Vault).

Generating the Signature

Compute the signature using the raw JSON body of your request and your Secret Key.

$payload = json_encode($data);
$secret = getenv('WEBHOOK_SECRET'); // Retrieve from secure storage

$signature = hash_hmac('sha256', $payload, $secret);

// Add $signature to the 'X-Webhook-Signature' header

use Illuminate\Support\Facades\Http;

$payload = [
    [
        "id"       => "ORD-2023-889",
        "article"  => "Wireless Headphones",
        "price"    => 199,
        "qte"      => 1,
        "receiver" => "Ahmed",
        "phone"    => "0600000000",
        "city"     => "Casablanca",
        "address"  => "Maarif Casablanca",
    ],
    [
        "id"       => "ORD-2023-890",
        "article"  => "USB-C Cable",
        "price"    => 199,
        "qte"      => 2,
        "receiver" => "Mohamed",
        "phone"    => "0600000000",
        "city"     => "Casablanca",
        "address"  => "",
    ],
];
$secret = config('services.platform.webhook_secret');

$signature = hash_hmac('sha256', json_encode($payload), $secret);

$response = Http::withHeaders([
    'X-Webhook-ClientId' => 'your-client-id',
    'X-Webhook-Signature' => $signature,
])->post('https://www.myleaddone.com/api/webhook/orders', $payload);

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

const payload = JSON.stringify([
  {
    "id": "ORD-2023-889",
    "article": "Wireless Headphones",
    "price": 199,
    "qte": 1,
    "receiver": "Ahmed",
    "phone": "0600000000",
    "city": "Casablanca",
    "address": "Maarif Casablanca",
  },
  {
    "id": "ORD-2023-890",
    "article": "USB-C Cable",
    "price": 199,
    "qte": 2,
    "receiver": "Mohamed",
    "phone": "0600000000",
    "city": "Casablanca",
    "address": ""
  }
]);
const secret = process.env.WEBHOOK_SECRET;

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

axios.post('https://www.myleaddone.com/api/webhook/orders', payload, {
    headers: {
        'Content-Type': 'application/json',
        'X-Webhook-ClientId': 'your-client-id',
        'X-Webhook-Signature': signature
    }
});

Webhook 1: Send Us Orders (Bulk)

POST

Clients use this webhook to send us orders so we can create them in our internal system.

This endpoint accepts an array of order objects, allowing you to sync multiple orders in a single request.

POST /api/webhook/orders

Payload Schema (Array of Objects)

Field	Type	Requirement	Description
id	String/Int	Required	Unique ID in your system.
article	String	Required	Product name or SKU.
price	Decimal	Required	Unit price.
phone	String	Required	Customer contact number.
qte	Integer	Optional	Quantity of the product.
receiver	String	Optional	Customer name.
city	String	Optional	Customer city.
address	String	Optional	Customer address.

[
  {
    "id": "ORD-2023-889",
    "article": "Wireless Headphones",
    "price": 199,
    "qte": 1,
    "receiver": "Ahmed",
    "phone": "0600000000",
    "city": "Casablanca",
    "address": "Maarif Casablanca",
  },
  {
    "id": "ORD-2023-890",
    "article": "USB-C Cable",
    "price": 199,
    "qte": 2,
    "receiver": "Mohamed",
    "phone": "0600000000",
    "city": "Casablanca",
    "address": ""
  }
]

curl -X POST https://www.myleaddone.com/api/webhook/orders \
-H "Content-Type: application/json" \
-H "X-Webhook-ClientId: YOUR_CLIENT_ID" \
-H "X-Webhook-Signature: YOUR_CALCULATED_SIGNATURE" \
-d '[
  {
    "id": "ORD-2023-889",
    "article": "Wireless Headphones",
    "price": 199,
    "phone": "0600000000"
  },
  {
    "id": "ORD-2023-890",
    "article": "USB-C Cable",
    "price": 199,
    "phone": "0600000000"
  }
]'

[
  {
    "success": true,
    "message": "Order received successfully",
    "order_id": "ORD-2023-889",
    "internal_id": "PLT-56789"
  },
  {
    "success": true,
    "message": "Order received successfully",
    "order_id": "ORD-2023-890",
    "internal_id": "PLT-56790"
  }
]

Webhook 2: Delivery & Tracking (Bulk)

POST

Usage: When you create orders in a delivery company system, send us the tracking details here. Also use this webhook whenever an order's delivery status changes (e.g., in-progress, delivered, returned).

POST /api/webhook/orders/tracking

Payload Example (Array)

You can update tracking for multiple orders simultaneously.

[
  {
    "id": "ORD-2023-889",
    "tracking_number": "TRK9988776655",
    "status": "out_for_delivery"
  },
  {
    "id": "ORD-2023-890",
    "tracking_number": "TRK1122334455",
    "status": "delivered"
  }
]

[
  {
    "success": true,
    "message": "Order updated successfully",
    "order_id": "ORD-2023-889",
    "internal_id": "PLT-56789"
  },
  {
    "success": true,
    "message": "Order updated successfully",
    "order_id": "ORD-2023-890",
    "internal_id": "PLT-56790"
  }
]

Laravel Implementation Example

// In your logic that handles delivery updates
$updates = [
    [
        'id' => 'ORD-001', 
        'tracking_number' => '12345', 
        'status' => 'shipped'
    ],
    [
        'id' => 'ORD-002', 
        'tracking_number' => '67890', 
        'status' => 'delivered'
    ]
];

// Calculate signature and send to the bulk endpoint
WebhookService::send("/orders/tracking", $updates);

Testing Your Webhooks

To ensure your integration is robust:

Use a tool like Webhook.site to inspect the headers and payloads you are sending before pointing them to our production URL.
Verify your HMAC signature logic by sending a request with a known body and secret, and checking if the hash matches.
Ensure your system handles 401 Unauthorized (bad signature) and 429 Too Many Requests (rate limits) gracefully.