Riferimento dei webhook

Vuoi avvisi email, Slack o Discord? Segui la guida alle notifiche.

Il payload

Ogni nuovo messaggio genera un HTTP POST al tuo URL con un Content-Type: application/json body:

{
  "id": "d8f2e71a20b4",
  "event": "message.created",
  "project": {
    "id": "prj_8f2k1q",
    "name": "acme-site"
  },
  "source": {
    "type": "form",
    "name": "Website contact form"
  },
  "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
  "reply": {
    "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
    "method": "open_conversation"
  },
  "message": {
    "id": "msg_4t9s2e",
    "from": {
      "name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "subject": "Question about pricing",
    "body": "Hi, quick question about the Pro plan...",
    "receivedAt": "2026-07-14T09:30:00.000Z"
  }
}

Campi

• event: message.created per un messaggio in arrivo, oppure notification.test per il pulsante Prova. Gli eventi di prova hanno un valore nullo per message e source.
• project: il progetto la cui casella ha ricevuto il messaggio (il suo id e name).
• source: da dove proviene il messaggio. type è "form" (il endpoint del modulo) oppure "email" (il indirizzo email di progetto); name è l’etichetta della fonte nella casella.
• message.from: del mittente email (sempre presente) e name (può essere vuoto se il mittente non l’ha indicato).
• message.subject: facoltativo nei moduli, quindi può essere vuoto.
• message.receivedAt: data e ora ISO 8601, UTC.
• reply.url: apre questa conversazione in Mailcontact, dove il proprietario può rispondere dopo l’accesso. Da solo non concede alcun accesso. Gli eventi di prova hanno un valore null per reply.

Consegna

• Rispondi velocemente. Restituisci uno stato 2xx appena accetti il payload ed esegui il lavoro effettivo in modo asincrono. Le consegne scadono dopo 10 secondi.
• Almeno una volta. Una risposta lenta o un errore temporaneo può far consegnare lo stesso messaggio più volte. Deduplica usando il campo del payload id, inviato anche in Idempotency-Key e X-Mailcontact-Event-Id header.
• Gli errori temporanei e HTTP 429 vengono ritentati fino a cinque tentativi, con attese esponenziali. Quasi tutte le altre risposte 4xx fermano la consegna.
• Usa un endpoint HTTPS pubblico sulla porta 443. Reti private, credenziali negli URL e reindirizzamenti sono rifiutati.

Sicurezza

I payload non sono ancora firmati: chi scopre l’URL webhook può inviarvi un POST falso. Segui queste precauzioni:

• Usa un percorso lungo e imprevedibile per l’URL del webhook e non pubblicarlo.
• Tratta ogni payload come dati non affidabili: convalidalo prima di agire.
• Non attivare azioni distruttive o irreversibili da un webhook non firmato. Notificare, registrare e accodare va bene; eliminare no.

La firma dei webhook non è attualmente disponibile. Ricevere un payload non prova chi l’ha inviato.

Webhook e canali di notifica a confronto

Usa il guida alle notifiche per avvisi email, Slack e Discord. Questo riferimento descrive il formato webhook generico per il tuo codice. Vedi prezzi per le offerte attuali.