Webhook ed eventi

I webhook dell'account inviano ciò che succede in tutto il tuo account a un URL che scegli tu, in tempo reale: un nuovo lead, un incontro prenotato, una trattativa che cambia fase. Sono ciò che usano dietro le quinte le integrazioni con Zapier e n8n, e puoi indirizzarli anche al tuo endpoint.

Si affiancano al webhook di progetto della pagina Risposte di un'email, che continua a funzionare come prima. Un webhook di progetto copre le interazioni di una sola email. Un webhook dell'account copre tutte le email, più gli eventi qui sotto, ed è firmato allo stesso modo.

Aggiungere un webhook

Vai in Sviluppatori nella dashboard e trova la scheda Webhook.
Inserisci l'URL dell'endpoint (un URL https:// pubblico) e spunta gli Eventi che ti servono.
Fai clic su Aggiungi webhook e copia il segreto di firma. Viene mostrato solo questa volta.

Ogni webhook mostra come è stato creato (Dashboard, API, Zapier o n8n), il suo stato e l'ultima consegna. Invia prova invia un esempio dell'evento scelto, con "test": true nel suo data. Elimina rimuove il webhook. Un account può averne fino a 50.

Solo il titolare dell'account può aggiungere o eliminare webhook, e potrebbe essergli chiesto di accedere di nuovo prima.

Eventi

Evento	Si attiva quando
`interaction.received`	Un destinatario interagisce con un'email: un voto, una valutazione, una risposta a un quiz, un clic tracciato, un acquisto e così via. Le ripetizioni deduplicate non lo attivano.
`form.submitted`	Viene inviato un modulo in un'email (`source: "email-form"`) o un modulo di iscrizione (`source: "signup-form"`).
`contact.created`	Un contatto viene aggiunto a una lista.
`contact.updated`	I campi di un contatto cambiano. Salvare dati identici non lo attiva.
`lead.hot`	Il punteggio di coinvolgimento di un contatto supera, salendo, la tua soglia per lead caldo.
`lead.new`	Arriva un nuovo lead da un modulo di iscrizione o da un modulo in un'email.
`booking.created`	Viene prenotato un incontro.
`booking.cancelled`	Una prenotazione viene annullata, con `cancelledBy`. Uno spostamento non attiva nessuno dei due eventi di prenotazione.
`deal.created`	Viene creata una trattativa, da qualsiasi parte: bacheca, regola automatica, journey, proposta o API.
`deal.stage_changed`	Una trattativa cambia fase, comprese vinta e persa.
`purchase.completed`	Un destinatario paga tramite un checkout nell'email.
`journey.completed`	Un contatto arriva alla fine di un journey. Chi esce prima non conta.

Gli eventi dei contatti si attivano con importazioni, moduli di iscrizione, API, sincronizzazioni e connettori IA. Una singola scrittura di oltre 500 contatti (per esempio una grande importazione CSV) non ne attiva nessuno, così un'importazione non avvia migliaia di workflow. Neanche le modifiche nella griglia dei contatti, i passaggi di journey Aggiorna campo e le risposte salvate li attivano.

lead.hot e lead.new si attivano indipendentemente dagli interruttori e dai limiti dei tuoi avvisi lead: l'iscrizione vale come consenso.

Payload

Ogni consegna è un POST JSON con la stessa busta:

{
  "id": "evt_8c1f…",
  "type": "deal.stage_changed",
  "createdAt": 1790000000000,
  "data": {
    "deal": {
      "id": "deal_abc123",
      "title": "Annual plan",
      "value": 1200,
      "currency": "USD",
      "pipelineId": "owner_default",
      "stageId": "proposal-sent",
      "stage": "Proposal sent",
      "status": "open",
      "source": "manual",
      "listId": "list_abc123",
      "rowId": "3f6c1b0e2d…",
      "email": "[email protected]"
    },
    "fromStageId": "meeting-booked"
  }
}

id è lo stesso a ogni consegna dello stesso evento ed è inviato anche nell'intestazione X-MailInApp-Idempotency-Key, quindi puoi scartare senza rischi una riconsegna già elaborata. createdAt è in millisecondi epoch.

Per vedere il data di ogni tipo di evento, chiama GET /api/v1/events/sample oppure usa Invia prova.

Verificare la firma

Le consegne portano le intestazioni X-MailInApp-Timestamp e X-MailInApp-Signature, calcolate esattamente come per un webhook di progetto. Verificale sul corpo grezzo con il tuo segreto di firma e rifiuta i timestamp più vecchi di qualche minuto. La documentazione del webhook di progetto contiene una funzione Node.js pronta all'uso.

Nuovi tentativi

Il tuo endpoint ha 5 secondi per rispondere con un 2xx. Qualsiasi altra cosa (timeout, stato di errore, reindirizzamento) è un errore, e la consegna viene ritentata automaticamente, a intervalli crescenti per diverse ore, con lo stesso corpo e la stessa chiave di idempotenza, verso l'URL attuale del webhook. Rispondi in fretta e fai il lavoro lento dopo.

Se il tuo endpoint risponde 410 Gone, il webhook viene disattivato. È così che i client REST Hooks annullano l'iscrizione.
Revocare una chiave API disattiva i webhook creati con essa.
Eliminare un webhook interrompe i suoi tentativi in sospeso.

Iscriversi tramite API

Zapier, n8n e il tuo codice possono gestire i webhook con una chiave API (Authorization: Bearer mia_live_…):

curl https://mailinapp.com/api/v1/webhooks \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'

La risposta 201 contiene l'id dell'iscrizione e il suo secret, che firma ogni consegna. Conservalo: non viene più restituito. GET /api/v1/webhooks elenca le tue iscrizioni e DELETE /api/v1/webhooks/{id} ne rimuove una. Basta un solo nome di evento sconosciuto perché l'intera richiesta venga rifiutata. Queste rotte accettano 30 richieste al minuto per chiave.

Il contratto completo è nella specifica OpenAPI.