Creare endpoint webhook
Registrare POST /webhooks/endpoints con scope webhooks:manage.
Registra un URL HTTPS pubblico per ricevere consegne firmate da MailingCore. Scope richiesto: webhooks:manage.
Creare endpoint
POST /webhooks/endpoints
Authorization: Bearer mc_live_xxxx
X-Tenant-Id: clxxxxxxxx
Content-Type: application/json
{
"url": "https://tuo-saas.com/webhooks/mailingcore",
"events": [
"contact.unsubscribed",
"email.bounced",
"email.complained"
],
"secret": "whsec_tuo_segreto_condiviso_min_32_chars"
}
| Campo | Regole |
|---|---|
url | Endpoint HTTPS pubblico sul tuo server |
events | Sottoinsieme dei tipi supportati — vedi Catalogo eventi |
secret | Chiave HMAC condivisa; salvala nelle variabili d'ambiente. Verifica X-MailingCore-Signature |
Risposta (201 Created) include l'id dell'endpoint e il secret (salvalo subito — non viene mostrato di nuovo per intero).
Provisionare API key
Crea una key con
webhooks:manage(più altri scope necessari all'integrazione). Vedi API key e scope.Implementare il receiver
Accetta
POST, leggi il raw body, verifica firma HMAC, rispondi 200 rapidamente.Registrare l'endpoint
Chiama
POST /webhooks/endpointscon l'URL di produzione e l'elenco minimo di eventi.Inviare evento di test
Attiva un invio o una disiscrizione in staging e conferma la consegna nel Log consegne.
Esempio: eventi per integratore B2B
Un SaaS che sincronizza contatti e lancia campagne di solito si iscrive a:
| Evento | Motivo |
|---|---|
contact.unsubscribed | Revocare il consenso newsletter nell'app dopo disiscrizione ospitata |
email.bounced (hard) | Segnare indirizzi non validi e bloccare invii futuri |
email.complained | Revocare consenso e avvisare gli operatori |
Opzionale: email.delivered, email.opened, email.clicked per metriche di engagement.
Gestire endpoint
| Azione | Endpoint |
|---|---|
| Elenca | GET /webhooks/endpoints |
| Disabilita / abilita | PATCH /webhooks/endpoints/:id/toggle |
| Log consegne | GET /webhooks/endpoints/:id/deliveries?limit=20 |
| Elimina | DELETE /webhooks/endpoints/:id |