DocumentazioneCatalogo eventi webhook
Catalogo eventi webhook
Riferimento payload per email.* e contact.unsubscribed.
Riferimento per i tipi di evento webhook in uscita. Registra endpoint in Webhook in uscita.
Tipi di evento
| Evento | Quando si attiva |
|---|---|
email.sent | Messaggio accettato e accodato al trasporto |
email.delivered | Il provider conferma consegna al MX destinatario |
email.opened | Pixel di tracking caricato (se abilitato) |
email.clicked | Link tracciato cliccato |
email.bounced | Bounce hard o soft dal provider |
email.complained | Reclamo spam (FBL) |
email.failed | Invio fallito prima o durante la consegna |
contact.unsubscribed | Il destinatario ha usato disiscrizione ospitata o API |
Forma dell'envelope
Ogni consegna e un POST firmato alla tua URL:
X-MailingCore-Signature: t=1719763200,v1=abc123...
Content-Type: application/json
{
"id": "evt_...",
"type": "email.delivered",
"createdAt": "2026-06-30T12:00:00.000Z",
"tenantId": "clxtenant...",
"data": { }
}
Verifica con firma HMAC prima di fidarti di data.
Dati email.* (campi comuni)
{
"emailLogId": "clxlog...",
"to": "[email protected]",
"subject": "Benvenuto",
"status": "DELIVERED",
"tags": ["welcome"],
"metadata": { "userId": "123" },
"templateVersionId": "clxversion...",
"occurredAt": "2026-06-30T12:00:01.000Z"
}
Campi aggiuntivi per evento:
| Evento | Campi extra |
|---|---|
email.bounced | bounceType (hard / soft), diagnostic |
email.complained | complaintFeedbackType |
email.opened | userAgent, ip (se raccolti) |
email.clicked | linkUrl, linkId |
Dati contact.unsubscribed
{
"contactId": "clxcontact...",
"externalId": "user-12345",
"email": "[email protected]",
"unsubscribedAt": "2026-06-30T12:00:00.000Z",
"source": "hosted_page"
}
Usalo per sincronizzare disiscrizioni nel CRM e fermare campagne future.
Suggerimenti di elaborazione
- Rispondi 200 entro pochi secondi; elabora in asincrono.
- Usa
id(oemailLogId) per deduplicazione — i retry sono attesi. - Su
email.bounced(hard) ocontact.unsubscribed, aggiungi l'indirizzo alla logica soppressioni locale.