Configurare i webhook

Published: 16 luglio 2026 · Last updated: 21 luglio 2026 · By Marcus Biel

I webhook consentono a Maildroppa di notificare un'altra applicazione quando accade qualcosa di importante nel tuo account.

Invece di chiedere ripetutamente a Maildroppa se un iscritto è stato creato, aggiornato, disiscritto o associato a un tag, la tua applicazione può ricevere una richiesta HTTPS poco dopo il verificarsi dell'evento.

La pagina Webhooks è il punto centrale per questa integrazione a livello di account. Puoi creare diversi endpoint, scegliere gli eventi ricevuti da ciascun endpoint, aggiungere intestazioni di autenticazione, testare la connessione, esaminare i tentativi di consegna e riprodurre un evento di produzione quando necessario.

Come funzionano i webhook dell'account

Un webhook dell'account segue questo processo:

1. In Maildroppa si verifica un evento, ad esempio la creazione di un iscritto.
2. Maildroppa individua ogni endpoint attivo iscritto a quell'evento.
3. Maildroppa crea una consegna per ogni endpoint corrispondente.
4. Il payload JSON viene firmato con il Signing secret del tuo account.
5. Maildroppa invia una richiesta HTTPS POST all'URL dell'endpoint salvato.
6. Il tuo endpoint verifica la firma, archivia o elabora l'evento e restituisce una risposta HTTP.
7. Maildroppa registra il risultato nella cronologia delle consegne e ritenta automaticamente gli errori temporanei.

Se diversi endpoint sono iscritti allo stesso evento, ciascun endpoint riceve la propria consegna. L'evento aziendale ha lo stesso Event ID per tutti, mentre ogni consegna ha un proprio Delivery ID.

I webhook dell'account sono diversi da un passaggio “Send a webhook” all'interno di un'Automation. I webhook dell'account ascoltano gli eventi selezionati dell'account in Maildroppa. Un webhook di un'Automation viene inviato solo quando un iscritto raggiunge quel determinato passaggio. Entrambi utilizzano il Signing secret dei webhook dell'account, quindi la rotazione del secret influisce su ogni ricevitore di webhook in uscita che verifica le firme Maildroppa.

Apertura della pagina Webhooks

Apri “Settings”, espandi “Developers” e seleziona “Webhooks”.

La pagina contiene tre aree principali:

• Signing secret
• Endpoints
• Delivery history per l'endpoint selezionato

Quando hai più di un endpoint, seleziona una riga dell'endpoint per visualizzarne la Delivery history. Se non ne hai selezionato esplicitamente uno, Maildroppa mostra la cronologia del primo endpoint nell'elenco.

Prima di creare un endpoint

Prepara un ricevitore sul tuo server prima di configurare Maildroppa. Il ricevitore dovrebbe:

• Essere disponibile tramite un URL HTTPS pubblico.
• Accettare richieste POST con un corpo application/json.
• Conservare il corpo grezzo della richiesta finché la firma Maildroppa non è stata verificata.
• Restituire uno stato 2xx solo dopo aver accettato l'evento in modo sicuro.
• Elaborare le consegne ripetute in modo idempotente utilizzando l'Event ID.
• Rispondere rapidamente invece di eseguire operazioni lente durante la richiesta.

Un approccio affidabile consiste nel verificare la richiesta, archiviare l'Event ID e il payload in una coda o un database durevole, restituire 200 o 204 ed eseguire successivamente l'azione aziendale.

Non esporre un computer di sviluppo, un indirizzo di rete locale o uno script non protetto come ricevitore di webhook in produzione. Maildroppa accetta solo destinazioni HTTPS pubbliche e verifica nuovamente la destinazione quando invia una consegna.

Passaggio 1: genera il Signing secret

Ogni richiesta webhook di Maildroppa è firmata. Il tuo ricevitore utilizza il Signing secret per verificare che la richiesta sia stata creata da Maildroppa e che il corpo non sia stato modificato durante il transito.

Nella parte superiore della pagina, il pannello Signing secret mostra uno di questi stati:

• Missing — Non esiste ancora alcun Signing secret.
• Ready — È configurato un Signing secret.
• Loading — Maildroppa sta recuperando lo stato attuale.

Fai clic su “Generate secret” quando lo stato è Missing.

Maildroppa mostra immediatamente il nuovo secret. Inizia con whsec_. Fai clic su “Copy” e conservalo nel gestore dei secret o nella configurazione protetta dell'ambiente utilizzata dal tuo ricevitore.

Il valore completo viene mostrato solo subito dopo la generazione o la rotazione. Quando ricarichi o lasci la pagina, Maildroppa mostra solo che esiste un secret e quando è stato aggiornato l'ultima volta. Il secret archiviato non viene mostrato nuovamente.

Se perdi il secret

Se il ricevitore non dispone più del secret attuale, fai clic su “Rotate secret” e salva il valore appena visualizzato.

La rotazione sostituisce immediatamente il secret precedente. Maildroppa non conserva entrambi i valori per un periodo di transizione. Aggiorna ogni ricevitore che utilizza questo secret dell'account prima di inviare altri test o affidarti alle consegne di produzione.

Le nuove consegne, i tentativi programmati, i test e le riproduzioni vengono firmati con il secret attuale al momento della richiesta HTTP. Ciò significa che una consegna creata prima della rotazione può comunque essere firmata con il nuovo secret quando viene tentata successivamente.

Tratta il secret come una password

Non inserire il Signing secret nel codice del browser, in un repository pubblico, in un URL, in una pagina di errore o in un normale log dell'applicazione.

Solo il ricevitore lato server ha bisogno del secret. Se ritieni che sia stato esposto, ruotalo e aggiorna immediatamente tutti i ricevitori.

Verifica della firma di un webhook

Ogni richiesta contiene queste intestazioni Maildroppa:

• X-Maildroppa-Event-Id — Identifica l'evento aziendale.
• X-Maildroppa-Delivery-Id — Identifica questa specifica consegna.
• X-Maildroppa-Timestamp — L'ora della firma in secondi Unix.
• X-Maildroppa-Signature — La firma HMAC versionata.

Maildroppa invia anche:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

La firma ha questo formato:

v1=<lowercase hexadecimal HMAC>

Maildroppa la crea con HMAC-SHA256. Il contenuto firmato è il timestamp, seguito da un punto, seguito dal corpo JSON grezzo esatto della richiesta:

<timestamp>.<raw request body>

Usa il Signing secret come chiave HMAC.

L'esempio seguente in Node.js mostra il passaggio essenziale di verifica. rawBody deve contenere i byte originali della richiesta, non JSON già analizzato e serializzato nuovamente.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Dopo aver verificato la firma, confronta anche il timestamp con l'ora del tuo server. Rifiuta le richieste al di fuori di una breve tolleranza scelta per la tua infrastruttura, ad esempio cinque minuti. Ciò riduce il rischio che una richiesta valida intercettata venga riprodotta molto più tardi.

Analizza ed elabora il JSON solo dopo che entrambi i controlli sono stati superati.

Cause comuni degli errori di firma

Una firma di solito non è valida per uno dei seguenti motivi:

• Il ricevitore utilizza un secret precedente dopo la rotazione.
• Il middleware ha analizzato o modificato il JSON prima del calcolo della firma.
• Il ricevitore firma solo il corpo e omette <timestamp>..
• Il timestamp viene trattato come una data formattata invece di usare il valore esatto dell'intestazione.
• Il prefisso v1= è omesso dal confronto.
• L'HMAC calcolato è codificato in modo diverso invece che in formato esadecimale minuscolo.

Registra l'Event ID e il Delivery ID quando la verifica non riesce, ma non registrare mai il Signing secret o i valori sensibili delle intestazioni personalizzate.

Passaggio 2: aggiungi un endpoint

Fai clic su “Add endpoint” nella sezione Endpoints.

L'editor contiene quattro parti:

• Endpoint URL
• Events
• Custom headers
• Active status

I nuovi endpoint iniziano come Active e tutti gli eventi mostrati nell'editor sono inizialmente selezionati. Controlla la selezione prima di salvare, affinché il ricevitore riceva solo le notifiche di cui ha effettivamente bisogno.

Configurazione dell'Endpoint URL

Inserisci l'URL pubblico completo che deve ricevere le richieste Maildroppa, ad esempio:

https://integrations.example.com/webhooks/maildroppa

L'URL deve soddisfare questi requisiti:

• Deve utilizzare https://.
• Deve contenere un hostname pubblico valido.
• Può contenere al massimo 2.048 caratteri.
• Non può contenere variabili modello con { o }.
• Non può contenere un nome utente o una password prima dell'hostname.
• Non può contenere un frammento URL che inizi con #.
• Deve utilizzare la porta HTTPS standard 443.
• Non può utilizzare localhost, un indirizzo IP diretto o un hostname che risolve verso una rete privata o riservata bloccata.

I parametri di query sono supportati, ma non inserire chiavi API o altri secret nell'URL. Gli URL sono visibili nell'elenco degli endpoint e nei dati delle consegne. Usa invece una Custom header per le credenziali.

Maildroppa non segue i reindirizzamenti. Salva la destinazione HTTPS finale anziché un URL che restituisce 301, 302, 307 o 308.

L'hostname di destinazione viene risolto nuovamente prima dell'invio. Un hostname che in seguito risolve verso un indirizzo privato o bloccato viene rifiutato anche se era valido quando l'endpoint è stato salvato.

Scelta degli eventi

Seleziona almeno un evento. Un endpoint riceve solo i tipi di evento selezionati nel suo editor.

La pagina offre queste opzioni di evento:

Subscriber Created — subscriber.created

Inviato quando un iscritto viene creato nell'account Maildroppa.

Usa questo evento per creare il contatto corrispondente in un CRM, una piattaforma di dati dei clienti, un database interno o un altro sistema che tenga conto delle autorizzazioni.

Non interpretare questo evento come prova che ogni iscrizione abbia completato il Double Opt-in. Lo stato dell'iscritto nel payload descrive lo stato attuale.

Subscriber Updated — subscriber.updated

Inviato quando cambiano le informazioni integrate dell'iscritto o i valori dei campi personalizzati.

Usa l'oggetto completo dell'iscritto nel payload come rappresentazione attuale in Maildroppa. Evita di presumere che sia cambiata una sola proprietà specifica.

Le assegnazioni e le rimozioni dei tag hanno tipi di evento propri, così possono essere gestite separatamente.

Subscriber Unsubscribed — subscriber.unsubscribed

Inviato quando l'iscritto passa allo stato unsubscribed tramite un'azione di disiscrizione.

Usa questo evento per sopprimere il contatto nei sistemi collegati. Non iscrivere nuovamente automaticamente la persona solo perché un altro sistema indica ancora il contatto come attivo.

Tag Added — subscriber.tag_added

Inviato quando un tag viene assegnato a un iscritto.

Il payload contiene l'iscritto e il tag coinvolti in questa modifica specifica.

Tag Removed — subscriber.tag_removed

Inviato quando un tag viene rimosso da un iscritto.

Il payload contiene l'iscritto aggiornato e il tag rimosso. Il tag rimosso viene fornito separatamente anche se non è più presente nell'array tags attuale dell'iscritto.

Form Submitted — form.submitted

Inviato quando un visitatore invia un modulo di iscrizione Maildroppa.

Consideralo un segnale di invio del modulo, non una conferma del completamento del Double Opt-in. Qualsiasi flusso di lavoro che richieda un'iscrizione confermata deve continuare a rispettare lo stato attuale dell'iscritto e il processo di conferma.

Usa endpoint separati quando le responsabilità differiscono

Puoi inviare eventi diversi a sistemi diversi. Ad esempio:

• Invia gli eventi degli iscritti e dei tag a un CRM.
• Invia gli eventi di disiscrizione a un servizio di soppressione.
• Invia gli eventi di invio dei moduli a una pipeline di analisi.

Gli endpoint separati riducono il traffico non necessario e rendono più semplice diagnosticare gli errori. Ogni endpoint dispone della propria selezione di eventi, URL, intestazioni personalizzate, stato attivo, test e Delivery history.

Aggiunta di Custom headers

Le Custom headers sono facoltative. Usale quando il ricevitore richiede una chiave API, un bearer token, un identificatore del tenant o un'altra intestazione fissa.

Fai clic su “Add header”, quindi inserisci Header name e Header value. Esempi adatti includono:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Puoi aggiungere fino a 20 intestazioni personalizzate.

Nomi delle intestazioni:

• Sono obbligatori.
• Possono contenere al massimo 128 caratteri.
• Devono utilizzare caratteri validi per i nomi delle intestazioni HTTP.
• Devono essere univoci indipendentemente dall'uso di maiuscole o minuscole.

Valori delle intestazioni:

• Sono obbligatori.
• Possono contenere al massimo 2.000 caratteri.
• Non possono contenere interruzioni di riga.

I seguenti nomi sono riservati e non possono essere sostituiti da un'intestazione personalizzata:

• Content-Type
• Content-Length
• Host
• User-Agent
• Qualsiasi nome che inizi con X-Maildroppa-

Ciò impedisce a un valore personalizzato di sostituire le intestazioni di consegna e firma di Maildroppa.

Come vengono archiviati i secret delle intestazioni

Maildroppa crittografa i valori delle intestazioni personalizzate prima di archiviarli. I valori salvati non vengono restituiti al browser in forma leggibile.

Quando modifichi successivamente l'endpoint, il campo del valore mostra “Stored value kept”. Lascialo vuoto quando il secret esistente deve rimanere invariato. Inserisci un nuovo valore per sostituirlo.

Se cambi il nome dell'intestazione, inserisci nuovamente il valore. Maildroppa conserva un secret archiviato solo finché il nome originale dell'intestazione rimane invariato.

La rimozione di una riga di intestazione elimina quell'intestazione dalle consegne future dopo il salvataggio dell'endpoint.

I valori delle intestazioni personalizzate sono considerati sensibili nelle informazioni sulle richieste archiviate. Nella Delivery history vengono mascherati anziché mostrati.

Impostazione dell'endpoint come attivo o inattivo

Lascia selezionato “Active” quando l'endpoint è pronto a ricevere immediatamente gli eventi.

Deselezionalo quando vuoi salvare la configurazione senza avviare le consegne. Potrai attivare l'endpoint in seguito dall'elenco degli endpoint.

Un endpoint inattivo:

• Non riceve gli eventi che si verificano successivamente.
• Non può inviare un Test webhook.
• Rimane visibile e modificabile.
• Mantiene disponibile la Delivery history esistente.

L'attivazione di un endpoint non recupera gli eventi verificatisi mentre era inattivo.

Fai clic su “Save” quando URL, selezione degli eventi, intestazioni e stato sono corretti.

Comprendere l'elenco degli endpoint

Ogni riga dell'endpoint mostra:

• L'URL di destinazione.
• Un badge Active o Inactive.
• I tipi di evento sottoscritti.
• Il numero di intestazioni personalizzate.
• L'ora dell'ultimo aggiornamento dell'endpoint.

Le azioni disponibili sono:

• On/Off — Attiva o disattiva l'endpoint.
• Test — Invia una richiesta di test immediata a un endpoint attivo.
• Edit — Modifica URL, eventi, intestazioni o stato attivo.
• Delete — Rimuove definitivamente la configurazione dell'endpoint dopo la conferma.

Seleziona la parte principale di una riga per aprire la Delivery history di quell'endpoint sotto l'elenco.

Come le modifiche salvate influiscono sulle consegne esistenti

Un evento dell'account crea una consegna con un'istantanea dell'URL dell'endpoint, del payload e delle intestazioni personalizzate in quel momento.

La modifica dell'URL o delle intestazioni personalizzate influisce sulle consegne create successivamente. Una consegna già accodata conserva la destinazione originale e la configurazione delle intestazioni archiviata.

La modifica degli eventi selezionati influisce solo sugli eventi che si verificano in seguito. Maildroppa non crea consegne retroattive per tipi di evento non selezionati quando l'evento si è verificato.

Il Signing secret è diverso: viene letto quando la richiesta HTTP viene preparata. Una consegna in attesa o una riproduzione può quindi utilizzare un Signing secret appena ruotato anche quando il payload e l'istantanea dell'endpoint sono stati creati in precedenza.

Test di un endpoint

Fai clic su “Test” su un endpoint attivo dopo aver preparato il ricevitore e il Signing secret.

Maildroppa invia immediatamente una richiesta firmata utilizzando l'URL dell'endpoint salvato e le intestazioni personalizzate salvate. Le modifiche non salvate in un editor aperto non fanno parte del test.

Il payload di test utilizza il tipo di evento webhook.test e imposta livemode su false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Gli ID e il timestamp generati sono diversi per ogni test reale.

Un test esegue esattamente un tentativo HTTP. Le consegne di test non vengono inserite nel programma di ritentativi di produzione e non possono essere riprodotte.

Al termine della richiesta, il pannello dei risultati mostra:

• Test success o Test failed
• Event ID
• Stato HTTP, quando è stata ricevuta una risposta
• Durata
• Delivery ID
• Informazioni sull'errore, quando disponibili
• Un estratto della risposta, quando il ricevitore ha restituito un corpo

Il test compare anche nella Delivery history con un badge Test. Usa il filtro “Test” per mostrare solo le richieste di test.

Comprendere il payload di produzione

Gli eventi dell'account in produzione utilizzano un involucro JSON comune:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Le proprietà di primo livello significano:

• id — L'Event ID. Corrisponde a X-Maildroppa-Event-Id.
• type — La chiave dell'evento selezionata nell'editor dell'endpoint.
• schema_version — La versione dello schema del payload. Usala per decidere come analizzare l'evento.
• created_at — L'ora di creazione del payload dell'evento, in UTC.
• livemode — true per gli eventi di produzione e false per gli eventi di test.
• data — Il contenuto specifico dell'evento.

Instrada gli eventi in base al valore esatto di type. Ignora le proprietà aggiuntive che la tua integrazione non necessita, così le aggiunte compatibili al payload non interromperanno il ricevitore.

Payload degli eventi degli iscritti

Gli eventi degli iscritti contengono la rappresentazione attuale dell'iscritto all'interno di data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields e tags sono array. Possono essere vuoti. Una proprietà dell'iscritto può anche essere null quando non esiste alcun valore, quindi il ricevitore deve seguire lo schema del payload invece di presumere che ogni valore opzionale del profilo sia presente.

Payload degli eventi dei tag

Gli eventi dei tag contengono sia l'iscritto sia il tag che ha causato l'evento:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Per subscriber.tag_removed, data.tag identifica comunque il tag rimosso, anche se l'array tags attuale dell'iscritto non lo contiene più.

Event ID, Delivery ID e idempotenza

L'Event ID e il Delivery ID hanno scopi diversi.

Event ID

L'Event ID identifica l'evento aziendale. Compare in:

• La proprietà id di primo livello del payload.
• L'intestazione della richiesta X-Maildroppa-Event-Id.
• Delivery history.

Lo stesso evento può essere inviato a diversi endpoint sottoscritti. Tali consegne condividono l'Event ID.

Anche i tentativi e le riproduzioni manuali mantengono l'Event ID originale. Archivia gli Event ID elaborati e rendi idempotente l'azione aziendale, così una richiesta ripetuta non crea contatti duplicati, non ripete un'azione irreversibile e non applica due volte la stessa modifica.

Delivery ID

Il Delivery ID identifica un record di consegna. Compare in:

• L'intestazione della richiesta X-Maildroppa-Delivery-Id.
• Delivery history.

Ogni consegna a un endpoint ha il proprio Delivery ID. Una riproduzione manuale crea un nuovo Delivery ID mantenendo l'Event ID originale.

Usa il Delivery ID per il tracciamento tecnico e l'assistenza. Usa l'Event ID per la deduplicazione a livello aziendale.

Restituzione della risposta HTTP corretta

Maildroppa classifica le risposte come segue:

• Qualsiasi risposta 2xx contrassegna la consegna come riuscita.
• Le risposte 408 Request Timeout, 429 Too Many Requests e 5xx sono errori temporanei e possono essere ritentate.
• Gli errori di rete che possono essere temporanei vengono ritentati.
• I reindirizzamenti e le altre risposte 3xx non vengono seguiti e sono trattati come errori definitivi.
• Le altre risposte 4xx sono trattate come errori definitivi e non vengono ritentate.

Restituisci 200, 202 o 204 solo quando l'evento è stato accettato in modo sicuro. Se l'elaborazione richiede tempo, archivia prima l'evento e restituisci una risposta di successo prima di eseguire il lavoro più lento in modo asincrono.

Non restituire un reindirizzamento verso un altro URL webhook. Configura invece l'URL finale in Maildroppa.

Programma dei ritentativi automatici

Le consegne di produzione possono effettuare fino a sette tentativi HTTP.

Dopo un errore ritentabile, Maildroppa programma il tentativo successivo con questi intervalli:

1. Dopo il tentativo 1: 1 minuto
2. Dopo il tentativo 2: 5 minuti
3. Dopo il tentativo 3: 30 minuti
4. Dopo il tentativo 4: 2 ore
5. Dopo il tentativo 5: 12 ore
6. Dopo il tentativo 6: 24 ore

Se il tentativo 7 riceve ancora un errore ritentabile, la consegna diventa Dead e non viene programmato alcun altro tentativo automatico.

Il programma viene calcolato dai singoli tentativi falliti. L'ora effettiva della consegna può essere leggermente successiva, poiché le consegne vengono elaborate in modo asincrono e sono inoltre soggette ai limiti di protezione del sistema.

Risolvi il problema temporaneo del ricevitore prima dell'orario “Next retry” visualizzato, quando possibile. Se i tentativi automatici sono terminati, usa Replay dopo che il ricevitore è tornato operativo.

Comprendere la Delivery history

La Delivery history appartiene all'endpoint attualmente selezionato. L'URL dell'endpoint appare nell'intestazione della sezione, così puoi confermare quale cronologia stai visualizzando.

Usa questi filtri:

• All — Mostra le consegne di produzione e di test.
• Production — Mostra solo le consegne di eventi live.
• Test — Mostra solo i test manuali.

Fai clic su “Refresh” per recuperare lo stato più recente. Non è necessario lasciare aperta la cronologia mentre Maildroppa invia o ritenta una consegna.

La pagina mostra le ultime 50 consegne corrispondenti al filtro selezionato.

Colonne delle consegne

Ogni riga contiene:

• Created — Quando è stato creato il record della consegna.
• State — Pending, Success, Failed o Dead.
• HTTP — Stato della risposta, numero di tentativi, durata e orario del tentativo successivo quando applicabile.
• Subscriber — L'indirizzo email dell'iscritto quando l'evento è collegato a un iscritto.
• Delivery — Tipo di evento, Event ID e Delivery ID.
• Actions — Replay quando la consegna è idonea.

Se non è stata effettuata alcuna richiesta HTTP, la colonna HTTP mostra “No HTTP attempt”. Può accadere quando Maildroppa rifiuta la richiesta prima dell'invio, ad esempio perché manca il Signing secret o la destinazione salvata non può più essere utilizzata in sicurezza.

Quando disponibili, la riga mostra anche un Error e un Response excerpt restituito dal ricevitore. Non restituire secret o dati personali sensibili nel corpo della risposta del webhook, perché una parte di tale risposta può comparire nel log delle consegne dell'account.

Stati delle consegne

Pending indica che la consegna è in attesa del primo tentativo o di un nuovo tentativo programmato. “Next retry” compare quando è stato programmato un altro tentativo.

Success indica che il ricevitore ha restituito una risposta 2xx. Non sono necessari altri tentativi automatici.

Failed indica che la consegna si è conclusa con un problema non ritentabile, è stata rifiutata prima di un tentativo HTTP o è stata interrotta prima dell'invio.

Dead indica che tutti i tentativi automatici per un problema ritentabile sono stati utilizzati senza ricevere una risposta riuscita.

Conservazione della cronologia

I record delle consegne vengono conservati per un periodo limitato:

• Consegne di produzione riuscite: 30 giorni
• Consegne di produzione non riuscite: 90 giorni
• Consegne di produzione Dead: 90 giorni
• Consegne di test: 30 giorni

Conserva i tuoi log di integrazione quando ti serve una cronologia di audit più lunga. Archivia Event ID e Delivery ID, ma evita di conservare inutilmente i secret.

Riproduzione di una consegna

Fai clic su “Replay” quando una consegna di produzione completata deve essere tentata nuovamente.

Replay è disponibile per le consegne di produzione nello stato Success, Failed o Dead. Non è disponibile mentre una consegna è Pending e le consegne di test non possono essere riprodotte.

Una riproduzione:

• Crea una nuova consegna Pending.
• Crea un nuovo Delivery ID.
• Mantiene l'Event ID originale.
• Mantiene il tipo di evento originale e il payload JSON.
• Utilizza l'URL di destinazione originale salvato e l'istantanea delle intestazioni personalizzate.
• Utilizza il Signing secret attuale quando viene preparata la nuova richiesta.

Replay non ricostruisce il payload dai dati attuali dell'iscritto. Invia nuovamente l'istantanea dell'evento originale. Ciò rende la riproduzione verificabile e impedisce che un evento storico cambi significato senza che tu te ne accorga.

È possibile avere una sola riproduzione Pending della stessa consegna di origine alla volta. Attendi il completamento della riproduzione prima di richiederne un'altra.

Assicurati che l'endpoint sia Active prima della riproduzione. Se l'endpoint è inattivo, la riproduzione accodata non può essere consegnata correttamente.

Poiché un ricevitore potrebbe aver completato l'azione aziendale anche se Maildroppa non ha ricevuto la risposta di successo, la riproduzione può produrre una richiesta duplicata. La deduplicazione tramite Event ID protegge il sistema collegato dalla ripetizione dell'azione.

Modifica di un endpoint

Fai clic su “Edit” per modificare URL, selezione degli eventi, intestazioni personalizzate o stato attivo.

Prima di salvare:

1. Conferma che il nuovo URL sia già disponibile.
2. Lascia vuoti i valori delle intestazioni salvate quando devono rimanere invariati.
3. Inserisci un nuovo valore per ogni intestazione rinominata.
4. Controlla la selezione degli eventi per non rimuovere accidentalmente le notifiche necessarie.
5. Salva e invia un nuovo Test webhook.

Ricorda che le consegne accodate conservano l'URL e l'istantanea delle intestazioni personalizzate esistenti. Testa la nuova configurazione per le consegne future invece di presumere che modifichi una richiesta già accodata.

Disattivazione di un endpoint

Usa l'interruttore On/Off quando vuoi mettere in pausa un'integrazione senza eliminare la configurazione e la cronologia.

Quando un endpoint viene impostato su Off:

• I nuovi eventi non vengono più accodati per quell'endpoint.
• Le consegne Pending che non sono già state prese in carico per l'invio vengono contrassegnate come Failed.
• Test viene disabilitato.
• L'endpoint rimane disponibile per la modifica e la successiva riattivazione.

Una richiesta già in corso al momento della disattivazione può comunque terminare. Dopo aver impostato l'endpoint su Off, controlla la Delivery history se questa distinzione è importante per la tua integrazione.

Gli eventi persi mentre l'endpoint è inattivo non vengono recuperati quando lo riattivi.

Eliminazione di un endpoint

Fai clic su “Delete” e conferma l'avviso quando l'endpoint non deve più esistere.

L'eliminazione rimuove l'endpoint dalla pagina, interrompe le consegne future degli eventi e fa fallire le consegne Pending che non erano già state prese in carico per l'invio.

Delete non serve per una pausa temporanea. Usa l'interruttore On/Off quando potresti aver bisogno nuovamente della configurazione o della cronologia visibile.

Prima dell'eliminazione, registra gli Event ID o i Delivery ID che ti servono ancora per l'audit dell'integrazione.

Risoluzione dei problemi

Impossibile salvare l'endpoint

Controlla che:

• L'URL inizi con https://.
• L'URL utilizzi un hostname pubblico e la porta 443.
• L'URL non contenga variabili, informazioni di accesso o frammenti.
• Sia selezionato almeno un evento.
• Ogni Custom header abbia un nome univoco e un valore.
• Le intestazioni Maildroppa e HTTP riservate non vengano utilizzate come nomi personalizzati.

Test è disabilitato

Test è disponibile solo per un endpoint Active. Attiva l'endpoint o modificalo e seleziona “Active”, quindi salva prima di eseguire il test.

Il test non mostra alcun tentativo HTTP

Genera un Signing secret se lo stato è Missing. Controlla inoltre che l'hostname di destinazione sia pubblico e risolva ancora correttamente.

Una richiesta può essere rifiutata prima dell'invio quando il secret, l'URL, le intestazioni personalizzate o il controllo di sicurezza della destinazione non sono validi.

Il ricevitore restituisce 401 o 403

Controlla il nome e la credenziale della Custom header salvata. Modifica l'endpoint e inserisci nuovamente il valore se è cambiato.

Verifica inoltre che il ricevitore non confonda la propria credenziale API con la firma Maildroppa. Un'intestazione di autorizzazione personalizzata e X-Maildroppa-Signature hanno scopi diversi e possono essere controllate separatamente.

Il ricevitore restituisce un reindirizzamento

Maildroppa non segue i reindirizzamenti. Sostituisci l'URL dell'endpoint con l'URL HTTPS pubblico finale ed esegui nuovamente il test.

La firma non corrisponde

Conferma che il ricevitore:

• Utilizzi il Signing secret attuale.
• Utilizzi il valore esatto di X-Maildroppa-Timestamp.
• Firmi <timestamp>.<raw request body>.
• Utilizzi HMAC-SHA256 e un output esadecimale minuscolo.
• Confronti il valore completo, incluso v1=.
• Esegua il confronto prima che l'analisi JSON modifichi il corpo.

Lo stesso evento arriva più di una volta

Può accadere dopo un'interruzione di rete, un tentativo automatico o una riproduzione manuale. È normale che i sistemi di consegna dei webhook offrano una consegna almeno una volta anziché esattamente una volta.

Usa l'Event ID come chiave di idempotenza. Restituisci una risposta 2xx quando ricevi nuovamente un Event ID già elaborato e non è necessaria alcuna azione aggiuntiva.

Una consegna è Pending

Controlla “Next retry” nella colonna HTTP. Un 408, 429, 5xx ritentabile o un errore di rete temporaneo rimane Pending fino al tentativo programmato successivo.

Fai clic su “Refresh” dopo l'orario del tentativo per caricare lo stato più recente.

Una consegna è Dead

Sono stati utilizzati tutti i tentativi automatici. Risolvi prima il problema del ricevitore, assicurati che l'endpoint sia Active, invia un Test webhook e poi usa Replay sulla consegna di produzione.

Checklist di produzione consigliata

Prima di affidarti a un endpoint in produzione, conferma tutti i seguenti punti:

1. Il ricevitore utilizza un URL HTTPS pubblico stabile con un certificato valido.
2. Il Signing secret è conservato fuori dal codice sorgente.
3. La firma viene verificata rispetto al corpo grezzo non modificato.
4. I timestamp obsoleti vengono rifiutati secondo una tolleranza documentata.
5. Il ricevitore archivia e deduplica gli Event ID.
6. Il ricevitore registra Event ID e Delivery ID per il tracciamento.
7. L'elaborazione lenta avviene dopo l'accettazione durevole dell'evento.
8. Viene restituita una risposta 2xx solo per gli eventi accettati.
9. Le credenziali personalizzate sono archiviate nelle intestazioni anziché nell'URL.
10. Sono selezionati solo i tipi di evento necessari.
11. Un Test webhook ha esito positivo e compare correttamente nella Delivery history.
12. Il monitoraggio avvisa quando le consegne di produzione iniziano a restituire errori.

Con queste protezioni, la pagina Webhooks offre entrambi gli elementi di un'integrazione affidabile: la consegna sicura degli eventi alla tua applicazione e una cronologia operativa chiara all'interno di Maildroppa.