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": trueEventi
| Tipo | Quando |
|---|---|
message.status | Cambio 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.received | Messaggio 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.status | Template 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.quality | Variazione della qualità del numero (GREEN, YELLOW, RED) e del limite di invio. Con RED il marketing va in pausa automatica. |
customer.status | Cambio 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'
iddell'evento. L'ordine non è garantito: usacreated_ate tieni lo stato più avanzato. - Solo URL https pubblici (porta 443 o 8443). I redirect non vengono seguiti.