Webhook non ricevuti

Verifica che l'evento sia sottoscritto

Apri l'endpoint e controlla l'elenco degli eventi selezionati. Un endpoint attivo che non sottoscrive l'evento non riceve nulla e non registra alcun errore: è la causa più frequente e la più facile da trascurare.

Verifica anche che l'endpoint sia in stato Attivo e non Sospeso: dopo troppi fallimenti consecutivi la piattaforma sospende automaticamente l'endpoint.

Controlla i log di consegna in Console

Il registro conserva 30 giorni di tentativi. Per ogni consegna trovi identificativo, evento, esito, codice HTTP restituito, durata, numero del tentativo e corpo della risposta del tuo server (troncato).

Verifica la raggiungibilità dell'endpoint

L'endpoint deve essere raggiungibile da Internet, non solo dalla tua rete aziendale. Prova da una rete esterna, per esempio dalla connessione dati del telefono:

curl -i -X POST "https://integrazioni.acme.it/blupantheon/eventi" \
  -H "Content-Type: application/json" \
  -H "X-BP-Event: session.ended" \
  -H "X-BP-Delivery: dlv_test_0001" \
  -H "X-BP-Signature: sha256=firma-di-prova" \
  -H "X-BP-Timestamp: 1788258000" \
  -d '{"event":"session.ended","data":{"sessionId":"ses_test"}}' \
  --max-time 15

Che cosa osservare:

• Codice HTTP restituito: deve essere un 2xx. Un 401 o 403 indica che la verifica della firma fallisce o che c'è un livello di autenticazione non previsto.
• Tempo totale: se supera i 10 secondi, la consegna andrà in timeout.
• Nessuna risposta: DNS non risolto, porta chiusa, firewall.

curl -o /dev/null -s -w "codice: %{http_code}  tempo: %{time_total}s\n" \
  -X POST "https://integrazioni.acme.it/blupantheon/eventi" \
  -H "Content-Type: application/json" -d '{}'

Verifica il certificato TLS

L'endpoint deve essere in HTTPS con certificato valido. Non sono accettati certificati autofirmati, scaduti, con nome host non corrispondente o con catena incompleta.

echo | openssl s_client -connect integrazioni.acme.it:443 -servername integrazioni.acme.it 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

Verifica di rispondere entro 10 secondi

Il timeout di consegna è di 10 secondi. Se il tuo endpoint elabora l'evento in modo sincrono (scrittura su CRM, invio email, elaborazioni pesanti) supererà facilmente il limite.

Il pattern corretto:

1. Ricevi la richiesta
2. Verifica la firma HMAC
3. Metti il payload in una coda o su una tabella di staging
4. Rispondi 200 immediatamente
5. Elabora in un processo separato

Verifica di restituire un codice 2xx

Qualsiasi codice diverso da 2xx è considerato un fallimento e attiva i ritentativi.

Verifica il calcolo della firma

Se restituisci 401 perché la firma non corrisponde, controlla nell'ordine:

Verifica i reindirizzamenti

I reindirizzamenti non vengono seguiti. Cause tipiche:

• reindirizzamento da http a https: registra direttamente l'URL https;
• reindirizzamento da dominio senza www a dominio con www o viceversa;
• barra finale aggiunta o rimossa dal tuo server;
• reindirizzamento verso una pagina di autenticazione.

Verifica con:

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  -X POST "https://integrazioni.acme.it/blupantheon/eventi"

Se il codice è 3xx, aggiorna l'URL dell'endpoint in Console con la destinazione finale.

Verifica le liste di indirizzi consentiti

Se il tuo firewall o WAF filtra per indirizzo IP di origine, autorizza gli intervalli di Blu Pantheon.

L'elenco aggiornato è pubblicato in Console. Le variazioni sono comunicate con 30 giorni di preavviso ai contatti tecnici del tenant.

Ripeti manualmente la consegna

Dopo aver corretto la causa, puoi ritrasmettere le consegne fallite: singolarmente, oppure in blocco selezionando un intervallo temporale. La ripetizione mantiene lo stesso identificativo X-BP-Delivery dell'originale, così il tuo sistema può riconoscerla e applicare l'idempotenza.

Le consegne restano ripetibili per 30 giorni.