De Palma Labs, distributore per l'Italia della piattaforma AYROMEX, Meta Tech Provider

Webhook

Ogni cliente può avere un URL di webhook, che riceve una POST JSON per ogni evento.

curl -X PUT https://api.depalmalabs.it/v1/customers/cus_xxxxxxxxxxxx/webhook \
  -H "Authorization: Bearer $DPL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tuo-gestionale.it/whatsapp/webhook"}'

# Il secret (whsec_...) è restituito solo alla prima configurazione o con "rotate_secret": true

Eventi

TipoQuando
message.statusCambio di stato di un messaggio inviato: sent, delivered, read, failed. Include categoria, se è a pagamento e route: mm_api se è passato dalla Marketing Messages API di Meta, cloud_api altrimenti.
message.receivedMessaggio in arrivo dal destinatario (testo, media, risposta a pulsante). Apre la finestra di 24 ore. Se il cliente preme un pulsante, button_payload contiene il payload del quick reply (template) o l'id del pulsante interattivo, text il testo del pulsante.
template.statusTemplate approvato, rifiutato (con motivo), in pausa o disattivato da Meta, oppure riclassificato (es. da UTILITY a MARKETING). Campi: name, language, status, previous_status, category, previous_category, rejection_reason.
customer.qualityVariazione della qualità del numero (GREEN, YELLOW, RED) e del limite di invio. Con RED il marketing va in pausa automatica.
customer.statusCambio di stato del cliente, indicato nel campo change. Oggi: change = marketing_terms quando cambiano i termini della Marketing Messages API del business, per esempio quando li accetta (campi marketing_terms e previous_marketing_terms). La prima lettura dopo il collegamento non genera eventi, salvo termini già accettati. Lo stato completo del cliente è sempre in GET /v1/customers/{id}.

Firma

Ogni richiesta ha l'header X-DPL-Signature: t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 di t + "." + corpo calcolato con il secret del webhook. Verifica la firma sul corpo grezzo, confronta in tempo costante e rifiuta timestamp più vecchi di 5 minuti.

<?php
// Webhook De Palma Labs: verifica firma, poi elabora. Rispondi 2xx entro 10 secondi.
$secret = getenv('DPL_WEBHOOK_SECRET'); // whsec_...
if (!$secret) { http_response_code(500); exit; } // senza secret ogni firma sarebbe falsificabile
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_DPL_SIGNATURE'] ?? '';

parse_str(str_replace(',', '&', $header), $parts); // t=...&v1=...
$t = (int)($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);

if (!$t || abs(time() - $t) > 300 || !hash_equals($expected, (string)($parts['v1'] ?? ''))) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Deduplica: lo stesso evento può arrivare più di una volta (consegna "almeno una volta").
// if (giaElaborato($event['id'])) { http_response_code(200); exit; }

switch ($event['type']) {
    case 'message.status':   // sent, delivered, read, failed
        aggiornaStato($event['data']['message_id'], $event['data']['status']);
        break;
    case 'message.received': // risposta del cliente
        salvaRisposta($event['data']['from'], $event['data']['text']);
        break;
    case 'template.status':  // APPROVED, REJECTED... oppure riclassificato (es. UTILITY -> MARKETING)
        $d = $event['data'];  // name, language, status, previous_status, category, previous_category, rejection_reason
        aggiornaTemplate($d['name'], $d['language'], $d['status'], $d['category']);
        if ($d['category'] !== $d['previous_category']) {
            // Meta ha cambiato categoria: cambia anche il prezzo dei messaggi con questo template.
            avvisaRiclassificazione($d['name'], $d['previous_category'], $d['category']);
        }
        break;
    case 'customer.quality': // GREEN, YELLOW, RED e limite di invio
    case 'customer.status':  // es. change = marketing_terms: termini Marketing Messages API accettati
        aggiornaCliente($event['customer_id'], $event['type'], $event['data']);
        break;
}
http_response_code(200);

Consegna e tentativi

  • Rispondi con un codice 2xx entro 10 secondi; se ti serve più tempo, elabora in coda.
  • In caso di errore ritentiamo dopo 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h e 12 h (circa un giorno in tutto). Dopo l'ultimo tentativo l'evento resta visibile nel portale come non consegnato.
  • Consegna "almeno una volta": deduplica sull'id dell'evento. L'ordine non è garantito: usa created_at e tieni lo stato più avanzato.
  • Solo URL https pubblici (porta 443 o 8443). I redirect non vengono seguiti.