Vai al contenuto

Funzionalità

Webhook

Ricevi callback HTTP in tempo reale quando si verificano eventi nel tuo workspace.

Panoramica

Notifuse gestisce due tipi di webhook:

  1. 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.

  2. 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
Impostazioni, Webhook: due endpoint con i loro eventi e il tasso di consegne riuscite

Creare una subscription webhook

Crea una subscription webhook nella console, da Impostazioni → Webhook → Aggiungi endpoint, dove scegli l’URL e i tipi di evento:

I tipi di evento di un endpoint webhook, scelti con le caselle di controllo, con Seleziona tutto

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

EventoDescrizione
contact.createdÈ stato aggiunto un nuovo contatto al workspace
contact.updatedI dati del contatto sono stati modificati
contact.deletedUn contatto è stato eliminato definitivamente

Eventi delle liste

EventoDescrizione
list.subscribedIl contatto si è iscritto a una lista
list.unsubscribedIl contatto si è disiscritto da una lista
list.confirmedIl contatto ha confermato l’iscrizione con double opt-in
list.resubscribedUn contatto disiscritto si è iscritto di nuovo
list.bouncedL’email al contatto ha generato un bounce
list.complainedIl contatto ha segnalato l’email come spam
list.pendingL’iscrizione del contatto è in attesa di conferma
list.removedIl contatto è stato rimosso dalla lista

Eventi dei segmenti

EventoDescrizione
segment.joinedIl contatto è entrato in un segmento (soddisfa i criteri del segmento)
segment.leftIl contatto è uscito da un segmento (non soddisfa più i criteri)

Eventi email

EventoDescrizione
email.sentL’email è stata inviata al contatto
email.deliveredIl server del destinatario ha confermato la consegna dell’email
email.openedIl contatto ha aperto l’email
email.clickedIl contatto ha cliccato un link nell’email
email.bouncedLa consegna dell’email non è riuscita
email.complainedIl contatto ha segnalato l’email come spam
email.unsubscribedIl contatto si è disiscritto dal link nell’email

Eventi personalizzati

EventoDescrizione
custom_event.createdÈ stato registrato un nuovo evento personalizzato
custom_event.updatedUn evento personalizzato è stato aggiornato
custom_event.deletedUn 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_ids si applica solo agli eventi list.*, segment_ids solo agli eventi segment.*. 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:

CampoDescrizione
enabledSe la subscription sta consegnando in questo momento
sourceCosa l’ha creata. Assente per una subscription creata da te; zapier per una creata dall’integrazione Zapier
consecutive_failuresI tentativi di consegna falliti di fila. Torna a zero al primo successo
failing_sinceQuando è iniziata la serie di errori in corso. Viene azzerato al primo successo
disabled_reasonPerché la subscription è stata disattivata in automatico. Assente per una che hai disattivato tu
last_delivery_atQuando è 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
  }
}
CampoDescrizione
idIdentificativo univoco della consegna del webhook
typeIl tipo di evento che ha attivato il webhook
timestampTimestamp ISO 8601 dell’invio del webhook
workspace_idIl workspace in cui si è verificato l’evento
dataI 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:

HeaderDescrizione
webhook-idIdentificativo univoco della consegna del webhook
webhook-timestampTimestamp Unix dell’invio del webhook
webhook-signatureFirma HMAC-SHA256 del payload

Verificare la firma

  1. Estrai il timestamp e la firma dagli header
  2. Costruisci il payload firmato: {webhook-id}.{webhook-timestamp}.{body}
  3. Calcola l’HMAC-SHA256 con il secret del tuo webhook
  4. 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:

TentativoAttesa dopo il precedente
1Immediato
230 secondi
31 minuto
42 minuti
55 minuti
615 minuti
730 minuti
81 ora
92 ore
106 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 Requests non 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. 404 non 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.regenerateSecret per ruotare il secret di firma
  • Vedi il riferimento API per la documentazione completa degli endpoint