Panoramica
Notifuse gestisce due tipi di webhook:
-
Webhook in entrata: callback dei provider email (Amazon SES, Mailgun, Postmark, ecc.) che informano Notifuse di bounce, reclami, consegne e altri eventi email. Vengono configurati in automatico quando imposti un’integrazione email.
-
Webhook in uscita: callback HTTP che Notifuse invia al tuo server quando si verificano degli eventi. Sono l’argomento di questa pagina.
Un webhook in uscita invia una richiesta HTTP POST al tuo server quando in Notifuse si verifica un determinato evento. Puoi usarli per:
- Sincronizzare i dati dei contatti con il tuo CRM o altri sistemi
- Avviare workflow in strumenti di automazione esterni
- Costruire integrazioni e dashboard personalizzate
- Reagire in tempo reale agli eventi di coinvolgimento sulle email
Creare una subscription webhook
Crea una subscription webhook nella console, da Impostazioni → Webhook → Aggiungi endpoint, dove scegli l’URL e i tipi di evento:
Oppure creala tramite API:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"name": "Production Webhook",
"url": "https://api.example.com/webhooks/notifuse",
"event_types": ["contact.created", "contact.updated", "email.sent"]
}'
Tipi di evento disponibili
Eventi dei contatti
| Evento | Descrizione |
|---|---|
contact.created | È stato aggiunto un nuovo contatto al workspace |
contact.updated | I dati del contatto sono stati modificati |
contact.deleted | Un contatto è stato eliminato definitivamente |
Eventi delle liste
| Evento | Descrizione |
|---|---|
list.subscribed | Il contatto si è iscritto a una lista |
list.unsubscribed | Il contatto si è disiscritto da una lista |
list.confirmed | Il contatto ha confermato l’iscrizione con double opt-in |
list.resubscribed | Un contatto disiscritto si è iscritto di nuovo |
list.bounced | L’email al contatto ha generato un bounce |
list.complained | Il contatto ha segnalato l’email come spam |
list.pending | L’iscrizione del contatto è in attesa di conferma |
list.removed | Il contatto è stato rimosso dalla lista |
Eventi dei segmenti
| Evento | Descrizione |
|---|---|
segment.joined | Il contatto è entrato in un segmento (soddisfa i criteri del segmento) |
segment.left | Il contatto è uscito da un segmento (non soddisfa più i criteri) |
Eventi email
| Evento | Descrizione |
|---|---|
email.sent | L’email è stata inviata al contatto |
email.delivered | Il server del destinatario ha confermato la consegna dell’email |
email.opened | Il contatto ha aperto l’email |
email.clicked | Il contatto ha cliccato un link nell’email |
email.bounced | La consegna dell’email non è riuscita |
email.complained | Il contatto ha segnalato l’email come spam |
email.unsubscribed | Il contatto si è disiscritto dal link nell’email |
Eventi personalizzati
| Evento | Descrizione |
|---|---|
custom_event.created | È stato registrato un nuovo evento personalizzato |
custom_event.updated | Un evento personalizzato è stato aggiornato |
custom_event.deleted | Un evento personalizzato è stato eliminato in modo logico (soft delete) |
Filtri sugli eventi personalizzati
Per gli eventi personalizzati puoi filtrare, se vuoi, per goal_types ed event_names:
{
"event_types": ["custom_event.created"],
"custom_event_filters": {
"goal_types": ["purchase", "subscription"],
"event_names": ["orders/fulfilled", "payment.succeeded"]
}
}
Filtrare per lista e segmento
Per impostazione predefinita una subscription agli eventi list.* riceve un evento per ogni lista del workspace, e una agli eventi segment.* per ogni segmento. Puoi restringerla con list_ids e segment_ids:
{
"event_types": ["list.subscribed", "list.unsubscribed", "segment.joined"],
"list_ids": ["newsletter", "product_updates"],
"segment_ids": ["vip_customers"]
}
list_idssi applica solo agli eventilist.*,segment_idssolo agli eventisegment.*. Nessuno dei due influisce sui tipi di evento dei contatti, delle email o personalizzati.- Omettere un filtro, o inviare un array vuoto, significa “ogni lista” o “ogni segmento”. Le subscription create prima dell’arrivo di questi filtri continuano a comportarsi così.
- Entrambi i filtri si possono modificare in seguito con
webhookSubscriptions.update.
Filtra ogni volta che puoi. Un workspace con liste grandi genera una consegna per contatto a ogni evento di lista, quindi una subscription che ha bisogno di una sola lista ma le riceve tutte fa lavorare la tua istanza per eventi che poi scarta.
Campi della subscription
Oltre al nome, all’URL e ai tipi di evento, una subscription riporta:
| Campo | Descrizione |
|---|---|
enabled | Se la subscription sta consegnando in questo momento |
source | Cosa l’ha creata. Assente per una subscription creata da te; zapier per una creata dall’integrazione Zapier |
consecutive_failures | I tentativi di consegna falliti di fila. Torna a zero al primo successo |
failing_since | Quando è iniziata la serie di errori in corso. Viene azzerato al primo successo |
disabled_reason | Perché la subscription è stata disattivata in automatico. Assente per una che hai disattivato tu |
last_delivery_at | Quando è riuscita l’ultima consegna |
Attenzione
Una subscription con un source è stata creata da un altro strumento, che ne è il proprietario. Eliminare da Notifuse una subscription creata da Zapier interrompe senza avvisi lo Zap collegato, e lo Zap non la ricrea da solo. Disattiva invece lo Zap in Zapier.
Quando Notifuse disattiva una subscription
Notifuse disattiva un endpoint che smette di rispondere solo quando valgono entrambe le condizioni: 20 errori consecutivi e una serie di errori che dura da più di due ore. Una breve interruzione (un deploy, un riavvio, un ricevitore irraggiungibile per poco durante un import) non disattiva mai la tua subscription, per quante consegne rifiuti nel frattempo. Quelle consegne vengono riprovate con il consueto backoff.
L’eccezione è un endpoint che risponde 410 Gone: viene disattivato subito, perché con quello stato il ricevitore dice che la subscription non esiste più.
Riattivare una subscription ne cancella la cronologia degli errori, quindi l’errore successivo non la disattiva di nuovo.
Dove Notifuse può consegnare
Il tuo endpoint deve essere raggiungibile da internet. Notifuse rifiuta di connettersi a indirizzi privati, di loopback, link-local e riservati, compreso l’endpoint dei metadati delle istanze cloud. Ripete il controllo a ogni reindirizzamento, quindi viene rifiutato anche un URL pubblico che reindirizza a uno interno. Una subscription il cui URL indica un indirizzo del genere viene respinta al salvataggio.
Nota
Solo self-hosting: per consegnare di proposito i webhook a un servizio della tua rete privata (un container sulla stessa rete Docker, uno strumento di automazione interno), imposta WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=true. Non impostarla su un deployment in cui qualcuno a cui non affideresti la tua rete interna può creare subscription o modificare automazioni. La stessa impostazione vale per i nodi webhook delle automazioni.
Una consegna rifiutata in questo modo viene riprovata come qualsiasi altro errore ma non conta mai ai fini della disattivazione della subscription, quindi basta correggere l’URL o l’impostazione per riprendere le consegne.
Struttura del payload
Tutti i payload dei webhook seguono questa struttura:
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
// Event-specific data
}
}
| Campo | Descrizione |
|---|---|
id | Identificativo univoco della consegna del webhook |
type | Il tipo di evento che ha attivato il webhook |
timestamp | Timestamp ISO 8601 dell’invio del webhook |
workspace_id | Il workspace in cui si è verificato l’evento |
data | I dati del payload specifici dell’evento |
Esempio: contatto creato
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"id": "contact_12345",
"external_id": "ext_67890",
"first_name": "John",
"last_name": "Doe",
"tags": ["newsletter", "customer"],
"tracking_opens_consent": "granted",
"tracking_clicks_consent": null,
"tracking_consent_updated_at": "2024-01-15T10:30:00Z",
"tracking_consent_source": "api",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Esempio: email inviata
{
"id": "delivery_def456",
"type": "email.sent",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T10:30:00Z"
}
}
Esempio: email aperta
{
"id": "delivery_ghi789",
"type": "email.opened",
"timestamp": "2024-01-15T11:45:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T11:45:00Z"
}
}
Esempio: ingresso in un segmento
{
"id": "delivery_jkl012",
"type": "segment.joined",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"contact_id": "contact_12345",
"segment_id": "seg_vip_customers",
"segment_name": "VIP Customers",
"created_at": "2024-01-15T10:30:00Z"
}
}
Verificare le firme dei webhook
Notifuse firma tutti i payload dei webhook secondo la specifica Standard Webhooks, con HMAC-SHA256.
Header
Ogni richiesta webhook include questi header:
| Header | Descrizione |
|---|---|
webhook-id | Identificativo univoco della consegna del webhook |
webhook-timestamp | Timestamp Unix dell’invio del webhook |
webhook-signature | Firma HMAC-SHA256 del payload |
Verificare la firma
- Estrai il timestamp e la firma dagli header
- Costruisci il payload firmato:
{webhook-id}.{webhook-timestamp}.{body} - Calcola l’HMAC-SHA256 con il secret del tuo webhook
- Confrontalo con la firma ricevuta
Esempi di codice
const crypto = require('crypto');
function verifyWebhook(payload, headers, secret) {
const msgId = headers['webhook-id'];
const msgTimestamp = headers['webhook-timestamp'];
const msgSignature = headers['webhook-signature'];
// Check timestamp is within 5 minutes
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(msgTimestamp)) > 300) {
throw new Error('Timestamp too old');
}
// Construct signed payload
const signedPayload = `${msgId}.${msgTimestamp}.${payload}`;
// Compute signature
const secretBytes = Buffer.from(secret.replace('whsec_', ''), 'base64');
const expectedSignature = crypto
.createHmac('sha256', secretBytes)
.update(signedPayload)
.digest('base64');
// Extract v1 signature
const signatures = msgSignature.split(' ');
for (const sig of signatures) {
const [version, signature] = sig.split(',');
if (version === 'v1' && signature === expectedSignature) {
return true;
}
}
throw new Error('Invalid signature');
}import hmac
import hashlib
import base64
import time
def verify_webhook(payload: str, headers: dict, secret: str) -> bool:
msg_id = headers.get('webhook-id')
msg_timestamp = headers.get('webhook-timestamp')
msg_signature = headers.get('webhook-signature')
# Check timestamp is within 5 minutes
now = int(time.time())
if abs(now - int(msg_timestamp)) > 300:
raise ValueError('Timestamp too old')
# Construct signed payload
signed_payload = f"{msg_id}.{msg_timestamp}.{payload}"
# Compute signature
secret_bytes = base64.b64decode(secret.replace('whsec_', ''))
expected_signature = base64.b64encode(
hmac.new(secret_bytes, signed_payload.encode(), hashlib.sha256).digest()
).decode()
# Extract v1 signature
for sig in msg_signature.split(' '):
version, signature = sig.split(',')
if version == 'v1' and signature == expected_signature:
return True
raise ValueError('Invalid signature')package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"errors"
"fmt"
"math"
"strconv"
"strings"
"time"
)
func VerifyWebhook(payload string, headers map[string]string, secret string) error {
msgID := headers["webhook-id"]
msgTimestamp := headers["webhook-timestamp"]
msgSignature := headers["webhook-signature"]
// Check timestamp is within 5 minutes
ts, _ := strconv.ParseInt(msgTimestamp, 10, 64)
now := time.Now().Unix()
if math.Abs(float64(now-ts)) > 300 {
return errors.New("timestamp too old")
}
// Construct signed payload
signedPayload := fmt.Sprintf("%s.%s.%s", msgID, msgTimestamp, payload)
// Compute signature
secretBytes, _ := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
h := hmac.New(sha256.New, secretBytes)
h.Write([]byte(signedPayload))
expectedSig := base64.StdEncoding.EncodeToString(h.Sum(nil))
// Extract v1 signature
for _, sig := range strings.Split(msgSignature, " ") {
parts := strings.SplitN(sig, ",", 2)
if len(parts) == 2 && parts[0] == "v1" && parts[1] == expectedSig {
return nil
}
}
return errors.New("invalid signature")
}<?php
function verifyWebhook(string $payload, array $headers, string $secret): bool {
$msgId = $headers['webhook-id'] ?? '';
$msgTimestamp = $headers['webhook-timestamp'] ?? '';
$msgSignature = $headers['webhook-signature'] ?? '';
// Check timestamp is within 5 minutes
$now = time();
if (abs($now - (int)$msgTimestamp) > 300) {
throw new Exception('Timestamp too old');
}
// Construct signed payload
$signedPayload = "{$msgId}.{$msgTimestamp}.{$payload}";
// Compute signature
$secretBytes = base64_decode(str_replace('whsec_', '', $secret));
$expectedSignature = base64_encode(
hash_hmac('sha256', $signedPayload, $secretBytes, true)
);
// Extract v1 signature
foreach (explode(' ', $msgSignature) as $sig) {
[$version, $signature] = explode(',', $sig, 2);
if ($version === 'v1' && $signature === $expectedSignature) {
return true;
}
}
throw new Exception('Invalid signature');
}Nuovi tentativi
Notifuse riprova le consegne non riuscite con un backoff esponenziale.
Calendario dei tentativi
Una consegna ha fino a 10 tentativi, l’ultimo circa 10 ore dopo il primo:
| Tentativo | Attesa dopo il precedente |
|---|---|
| 1 | Immediato |
| 2 | 30 secondi |
| 3 | 1 minuto |
| 4 | 2 minuti |
| 5 | 5 minuti |
| 6 | 15 minuti |
| 7 | 30 minuti |
| 8 | 1 ora |
| 9 | 2 ore |
| 10 | 6 ore |
Se fallisce anche il decimo tentativo, la consegna viene segnata come fallita e non viene più riprovata.
Criteri di successo
Una consegna riesce quando il tuo endpoint restituisce un codice di stato HTTP 2xx (200-299).
Condizioni di errore
Un tentativo di consegna fallisce se:
- Il tuo endpoint restituisce un codice di stato diverso da 2xx
- Il tuo endpoint impiega più di 10 secondi a rispondere
- L’endpoint è irraggiungibile (errore DNS, connessione rifiutata, ecc.)
Disattivazione automatica
Un endpoint che è stato spostato, dismesso o ha perso il suo record DNS non torna da solo, e Notifuse non continua ad accodare consegne per quell’endpoint.
Dopo una lunga serie di errori consecutivi, Notifuse disattiva la subscription e vi registra il motivo, così puoi distinguerla da una che hai disattivato tu. Il contatore è per subscription e una sola consegna riuscita lo riporta a zero, quindi viene disattivato solo un endpoint che fallisce in modo persistente.
Due risposte hanno un trattamento particolare:
429 Too Many Requestsnon conta mai come errore. Significa che il tuo server chiede meno richieste, e un workspace così attivo da essere limitato non deve perdere la sua integrazione per questo. La consegna viene riprovata secondo il calendario normale.410 Goneè definitivo alla prima risposta. È il modo standard con cui un ricevitore dice “questa subscription è morta, smetti di inviare”, quindi la subscription viene chiusa subito, senza la consueta serie di errori. Una subscription creata da te viene disattivata con quel motivo registrato; una creata da un altro strumento, come Zapier, viene eliminata del tutto, perché lo strumento la ricrea quando gli serve.404non viene trattato così: un endpoint che manca per poco viene riprovato come qualsiasi altro errore.
Per riattivare una subscription disattivata, correggi l’endpoint e riabilitala.
Nota
Una subscription disattivata scarta gli eventi invece di metterli in coda. Le consegne previste mentre è disattivata, che l’abbia disattivata tu o Notifuse, vengono segnate come fallite nel log delle consegne e non vengono ripetute quando la riattivi. Per recuperare gli eventi di un’interruzione, leggili tramite API.
Eliminare una subscription
Eliminare una subscription scarta anche le consegne ancora in coda per quella subscription, quindi non resta nulla da riprovare né una coda da svuotare prima.
Se prevedi di rimettere in funzione l’endpoint, disattiva la subscription invece di eliminarla: la disattivazione è reversibile e conserva la subscription con il suo secret di firma e la cronologia delle consegne. Una subscription eliminata non si può ripristinare, e ricrearla genera un nuovo secret di firma.
Buone pratiche
Rispondi subito con un 2xx
Restituisci una risposta di successo il prima possibile, ed elabora il payload in modo asincrono se serve:
// Good: Acknowledge quickly, process later
app.post('/webhooks/notifuse', async (req, res) => {
// Quickly validate signature
verifyWebhook(req.body, req.headers, SECRET);
// Queue for async processing
await queue.add('process-webhook', req.body);
// Respond immediately
res.status(200).json({ received: true });
});
Gestisci le consegne duplicate
In rari casi un webhook viene consegnato più di una volta. Usa l’header webhook-id per l’idempotenza:
app.post('/webhooks/notifuse', async (req, res) => {
const webhookId = req.headers['webhook-id'];
// Check if we've already processed this webhook
if (await hasProcessed(webhookId)) {
return res.status(200).json({ received: true, duplicate: true });
}
// Mark as processed before handling
await markProcessed(webhookId);
// Process the webhook
await processWebhook(req.body);
res.status(200).json({ received: true });
});
Verifica le firme
In produzione verifica sempre le firme dei webhook, per assicurarti che le richieste arrivino da Notifuse.
Tieni d’occhio le consegne non riuscite
Nella console, Impostazioni → Webhook mostra per ogni subscription il tasso di successo degli ultimi 7 giorni e l’ultima consegna riuscita. Apri una subscription per vedere le consegne riuscite e fallite delle ultime 24 ore o degli ultimi 7 giorni, e scegli Vedi le consegne per elencarle nei log.
Tramite API, aggiungi status (pending, delivering, delivered o failed) per elencare solo le consegne in quello stato; qualsiasi altro valore restituisce 400. failed include anche le consegne in attesa di un nuovo tentativo, che tornano a delivering quando vengono rinviate, quindi una consegna elencata come fallita può ancora riuscire:
curl "https://your-instance.com/api/webhookSubscriptions.deliveries?workspace_id=ws_123&subscription_id=whsub_456&status=failed" \
-H "Authorization: Bearer YOUR_API_KEY"
Provare i webhook
Inviare un webhook di prova
Usa l’endpoint di test per verificare la configurazione del webhook:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.test" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"id": "whsub_a1b2c3d4e5f6",
"event_type": "contact.created"
}'
Il parametro facoltativo event_type fa inviare al test un payload di esempio realistico per quel tipo di evento. Senza di esso, il test invia un payload generico.
Sviluppo in locale
Per lo sviluppo in locale, usa strumenti come ngrok o localtunnel per esporre il tuo server locale:
# Start ngrok
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/notifuse
Permessi
Le subscription in uscita seguono il permesso Subscription Webhook: Lettura elenca le subscription, ne apre una e mostra la cronologia delle consegne, compresi il payload di ogni evento e lo stato e il corpo della risposta dell’endpoint. Scrittura crea, aggiorna, elimina, attiva e disattiva le subscription e lancia una consegna di prova, che conta come scrittura perché fa chiamare il tuo server.
Le callback in entrata dei provider seguono il permesso Eventi Webhook: Lettura mostra le callback grezze che i tuoi provider email hanno rimandato a Notifuse, compresi gli indirizzi dei destinatari e la diagnostica dei provider. La scrittura su Eventi Webhook oggi non controlla nulla: le righe arrivano sulle route di callback dei provider, che non hanno sessione e non verificano alcun permesso, quindi concederla non dà nulla. La console la mostra concessa e bloccata.
Il catalogo dei tipi di evento disponibili non richiede permessi: qualsiasi membro o chiave autenticati può consultarlo.
Due azioni restano riservate al proprietario del workspace, qualunque permesso abbiano un membro o una API key:
- Rigenerare il secret di firma di una subscription. Il secret è anche nascosto a tutti tranne che al proprietario, quindi la lettura su Subscription Webhook non lo espone mai: un membro può elencare le subscription e ispezionare le consegne senza vedere la chiave che firma quei payload.
- Registrare i webhook presso un provider email, perché usa le credenziali del provider salvate nella tua integrazione.
Attenzione
La Scrittura su Subscription Webhook arriva più lontano di quanto suggerisca il nome. Una subscription sceglie gli eventi che riceve, quindi chi ha questo permesso può iscriversi agli eventi dei contatti e delle email e farsi consegnare quei dati a un URL di sua scelta. Concedilo come concederesti l’accesso in lettura ai contatti e alla cronologia dei messaggi che stanno dietro a quegli eventi.
Note
- In produzione i webhook richiedono endpoint HTTPS
- Il secret di firma viene generato in automatico quando crei una subscription
- Usa
webhookSubscriptions.regenerateSecretper ruotare il secret di firma - Vedi il riferimento API per la documentazione completa degli endpoint
