Vue d’ensemble
Notifuse gère deux types de webhooks :
-
Webhooks entrants : les appels des fournisseurs d’email (Amazon SES, Mailgun, Postmark, etc.) qui informent Notifuse des rebonds, des plaintes, des livraisons et d’autres événements d’email. Ils sont configurés automatiquement quand vous mettez en place une intégration d’email.
-
Webhooks sortants : les appels HTTP que Notifuse envoie à votre serveur quand des événements se produisent. Cette page porte sur eux.
Un webhook sortant envoie une requête HTTP POST à votre serveur quand un événement donné se produit dans Notifuse. Servez-vous-en pour :
- synchroniser les données des contacts avec votre CRM ou d’autres systèmes ;
- déclencher des workflows dans des outils d’automatisation externes ;
- construire des intégrations et des tableaux de bord sur mesure ;
- réagir en temps réel aux événements d’engagement sur les emails.
Créer un abonnement webhook
Créez un abonnement webhook dans la console, depuis Paramètres → Webhooks → Ajouter un point d’accès, où vous choisissez l’URL et les types d’événements :
Ou créez-le par l’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"]
}'
Types d’événements disponibles
Événements de contact
| Événement | Description |
|---|---|
contact.created | Un nouveau contact a été ajouté à l’espace de travail |
contact.updated | Les données d’un contact ont été modifiées |
contact.deleted | Un contact a été supprimé définitivement |
Événements de liste
| Événement | Description |
|---|---|
list.subscribed | Le contact s’est abonné à une liste |
list.unsubscribed | Le contact s’est désabonné d’une liste |
list.confirmed | Le contact a confirmé son abonnement en double opt-in |
list.resubscribed | Un contact désabonné s’est réabonné |
list.bounced | L’email envoyé au contact a rebondi |
list.complained | Le contact a signalé l’email comme spam |
list.pending | L’abonnement du contact attend une confirmation |
list.removed | Le contact a été retiré de la liste |
Événements de segment
| Événement | Description |
|---|---|
segment.joined | Le contact est entré dans un segment (il remplit ses critères) |
segment.left | Le contact a quitté un segment (il ne remplit plus ses critères) |
Événements d’email
| Événement | Description |
|---|---|
email.sent | L’email a été envoyé au contact |
email.delivered | Le serveur du destinataire a confirmé la livraison de l’email |
email.opened | Le contact a ouvert l’email |
email.clicked | Le contact a cliqué sur un lien de l’email |
email.bounced | La livraison de l’email a échoué |
email.complained | Le contact a signalé l’email comme spam |
email.unsubscribed | Le contact s’est désabonné via le lien de l’email |
Événements personnalisés
| Événement | Description |
|---|---|
custom_event.created | Un nouvel événement personnalisé a été enregistré |
custom_event.updated | Un événement personnalisé a été mis à jour |
custom_event.deleted | Un événement personnalisé a été supprimé de façon logique (soft delete) |
Filtres d’événements personnalisés
Pour les événements personnalisés, vous pouvez filtrer en option par goal_types et event_names :
{
"event_types": ["custom_event.created"],
"custom_event_filters": {
"goal_types": ["purchase", "subscription"],
"event_names": ["orders/fulfilled", "payment.succeeded"]
}
}
Filtrer par liste et par segment
Par défaut, un abonnement aux événements list.* reçoit un événement pour chaque liste de l’espace de travail, et un abonnement aux événements segment.* pour chaque segment. Restreignez-le avec list_ids et segment_ids :
{
"event_types": ["list.subscribed", "list.unsubscribed", "segment.joined"],
"list_ids": ["newsletter", "product_updates"],
"segment_ids": ["vip_customers"]
}
list_idsne s’applique qu’aux événementslist.*,segment_idsqu’aux événementssegment.*. Aucun des deux n’agit sur les types d’événements de contact, d’email ou personnalisés.- Omettre un filtre, ou envoyer un tableau vide, signifie « toutes les listes » ou « tous les segments ». Les abonnements créés avant l’arrivée de ces filtres continuent de se comporter ainsi.
- Les deux filtres peuvent être modifiés plus tard avec
webhookSubscriptions.update.
Filtrez chaque fois que c’est possible. Un espace de travail avec de grandes listes génère une livraison par contact pour chaque événement de liste : un abonnement qui n’a besoin que d’une liste mais les reçoit toutes fait travailler votre instance pour des événements qu’il jette.
Champs d’un abonnement
En plus de son nom, de son URL et de ses types d’événements, un abonnement indique :
| Champ | Description |
|---|---|
enabled | Si l’abonnement livre actuellement |
source | Ce qui l’a créé. Absent pour un abonnement que vous avez créé vous-même ; zapier pour un abonnement créé par l’intégration Zapier |
consecutive_failures | Les tentatives de livraison qui ont échoué d’affilée. Remis à zéro par le premier succès |
failing_since | Le début de la série d’échecs en cours. Effacé par le premier succès |
disabled_reason | Pourquoi l’abonnement a été désactivé automatiquement. Absent pour un abonnement que vous avez désactivé vous-même |
last_delivery_at | La date de la dernière livraison réussie |
Attention
Un abonnement qui porte une source a été créé par un autre outil, qui en est propriétaire. Supprimer depuis Notifuse un abonnement créé par Zapier casse sans prévenir le Zap qui l’utilise, et le Zap ne le recrée pas de lui-même. Désactivez plutôt le Zap dans Zapier.
Quand Notifuse désactive un abonnement
Notifuse ne retire un point d’accès qui ne répond plus que si les deux conditions sont réunies : 20 échecs consécutifs, et une série d’échecs de plus de deux heures. Une courte interruption (un déploiement, un redémarrage, un récepteur brièvement injoignable pendant un import) ne désactive jamais votre abonnement, quel que soit le nombre de livraisons refusées entre-temps. Ces livraisons sont réessayées selon le délai habituel.
L’exception est un point d’accès qui répond 410 Gone : il est retiré immédiatement, car ce statut signifie que le récepteur déclare que l’abonnement n’existe plus.
Réactiver un abonnement efface son historique d’échecs, si bien que l’échec suivant ne le retire pas de nouveau.
Où Notifuse peut livrer
Votre point d’accès doit être joignable depuis l’internet public. Notifuse refuse de se connecter aux adresses privées, de bouclage, link-local et réservées, y compris le point d’accès des métadonnées des instances cloud. Il vérifie de nouveau à chaque redirection : une URL publique qui redirige vers une adresse interne est donc refusée elle aussi. Un abonnement dont l’URL désigne une telle adresse est rejeté à l’enregistrement.
Note
Auto-hébergement uniquement : pour livrer volontairement des webhooks à un service de votre propre réseau privé (un conteneur sur le même réseau Docker, un outil d’automatisation interne), définissez WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=true. Laissez-la non définie sur tout déploiement où une personne à qui vous ne confieriez pas votre réseau interne peut créer des abonnements ou modifier des automations. Le même réglage couvre les nœuds webhook des automations.
Une livraison refusée de cette façon est réessayée comme tout autre échec, mais ne compte jamais pour la désactivation de l’abonnement : corriger l’URL ou le réglage suffit à relancer la livraison.
Structure du payload
Tous les payloads de webhook suivent cette structure :
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
// Event-specific data
}
}
| Champ | Description |
|---|---|
id | Identifiant unique de la livraison du webhook |
type | Le type d’événement qui a déclenché le webhook |
timestamp | Horodatage ISO 8601 de l’envoi du webhook |
workspace_id | L’espace de travail où l’événement s’est produit |
data | Les données propres à l’événement |
Exemple : contact créé
{
"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"
}
}
Exemple : email envoyé
{
"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"
}
}
Exemple : email ouvert
{
"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"
}
}
Exemple : entrée dans un segment
{
"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"
}
}
Vérifier les signatures des webhooks
Notifuse signe tous les payloads de webhook selon la spécification Standard Webhooks, avec HMAC-SHA256.
En-têtes
Chaque requête de webhook contient ces en-têtes :
| En-tête | Description |
|---|---|
webhook-id | Identifiant unique de la livraison du webhook |
webhook-timestamp | Horodatage Unix de l’envoi du webhook |
webhook-signature | Signature HMAC-SHA256 du payload |
Vérifier la signature
- Récupérez l’horodatage et la signature dans les en-têtes
- Construisez le payload signé :
{webhook-id}.{webhook-timestamp}.{body} - Calculez le HMAC-SHA256 avec le secret de votre webhook
- Comparez le résultat à la signature reçue
Exemples de code
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');
}Nouvelles tentatives
Notifuse réessaie les livraisons en échec avec un délai exponentiel.
Calendrier des tentatives
Une livraison a droit à 10 tentatives au plus, la dernière environ 10 heures après la première :
| Tentative | Délai après la précédente |
|---|---|
| 1 | Immédiat |
| 2 | 30 secondes |
| 3 | 1 minute |
| 4 | 2 minutes |
| 5 | 5 minutes |
| 6 | 15 minutes |
| 7 | 30 minutes |
| 8 | 1 heure |
| 9 | 2 heures |
| 10 | 6 heures |
Si la 10e tentative échoue aussi, la livraison est marquée en échec et n’est plus réessayée.
Critères de succès
Une livraison réussit quand votre point d’accès renvoie un code de statut HTTP 2xx (200-299).
Conditions d’échec
Une tentative de livraison échoue si :
- votre point d’accès renvoie un code de statut autre que 2xx ;
- votre point d’accès met plus de 10 secondes à répondre ;
- le point d’accès est injoignable (erreur DNS, connexion refusée, etc.).
Désactivation automatique
Un point d’accès qui a déménagé, a été mis hors service ou a perdu son enregistrement DNS ne revient pas tout seul, et Notifuse ne met pas en file des livraisons pour lui indéfiniment.
Après une longue série d’échecs d’affilée, Notifuse désactive l’abonnement et y enregistre la raison, pour que vous puissiez le distinguer d’un abonnement que vous avez désactivé vous-même. Le compteur est propre à chaque abonnement et une seule livraison réussie le remet à zéro : seul un point d’accès qui échoue durablement est désactivé.
Deux réponses sont traitées à part :
429 Too Many Requestsne compte jamais comme un échec. Ce code signifie que votre serveur demande moins de requêtes, et un espace de travail assez actif pour être limité ne doit pas perdre son intégration pour autant. La livraison est réessayée selon le calendrier normal.410 Goneest définitif dès la première réponse. C’est la façon standard pour un récepteur de dire « cet abonnement est mort, arrêtez d’envoyer » : l’abonnement est donc retiré immédiatement, sans la série d’échecs habituelle. Un abonnement que vous avez créé est désactivé avec cette raison enregistrée ; un abonnement créé par un autre outil, comme Zapier, est supprimé purement et simplement, car l’outil le recrée quand il en a besoin.404n’est pas traité ainsi : un point d’accès brièvement absent est réessayé comme pour tout autre échec.
Pour rétablir un abonnement désactivé, corrigez le point d’accès et réactivez l’abonnement.
Note
Un abonnement désactivé perd les événements au lieu de les mettre en file. Les livraisons prévues pendant qu’il est désactivé, que ce soit par vous ou par Notifuse, sont marquées en échec dans le journal des livraisons et ne sont pas rejouées quand vous le réactivez. Pour récupérer les événements d’une interruption, lisez-les depuis l’API.
Supprimer un abonnement
Supprimer un abonnement supprime aussi les livraisons encore en file pour lui : il ne reste rien à réessayer ni de file à vider au préalable.
Si vous comptez rétablir le point d’accès, désactivez l’abonnement au lieu de le supprimer : la désactivation est réversible et conserve l’abonnement avec son secret de signature et son historique de livraisons. Un abonnement supprimé ne peut pas être restauré, et le recréer génère un nouveau secret de signature.
Bonnes pratiques
Renvoyer 2xx rapidement
Renvoyez une réponse de succès le plus vite possible, et traitez le payload de façon asynchrone si nécessaire :
// 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 });
});
Gérer les livraisons en double
Dans de rares cas, un webhook est livré plus d’une fois. Utilisez l’en-tête webhook-id pour l’idempotence :
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 });
});
Vérifier les signatures
Vérifiez toujours les signatures des webhooks en production, pour vous assurer que les requêtes viennent bien de Notifuse.
Surveiller les échecs de livraison
Dans la console, Paramètres → Webhooks affiche pour chaque abonnement son taux de réussite sur les 7 derniers jours et sa dernière livraison réussie. Ouvrez un abonnement pour voir ses livraisons réussies et en échec sur les dernières 24 heures ou les 7 derniers jours, et choisissez Voir les livraisons pour les lister dans les logs.
Par l’API, ajoutez status (pending, delivering, delivered ou failed) pour ne lister que les livraisons dans ce statut ; toute autre valeur renvoie une erreur 400. failed comprend aussi les livraisons qui attendent une nouvelle tentative, qui repassent à delivering quand elles sont renvoyées : une livraison listée en échec peut donc encore réussir :
curl "https://your-instance.com/api/webhookSubscriptions.deliveries?workspace_id=ws_123&subscription_id=whsub_456&status=failed" \
-H "Authorization: Bearer YOUR_API_KEY"
Tester les webhooks
Envoyer un webhook de test
Utilisez le point d’accès de test pour vérifier la configuration de votre 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"
}'
Le paramètre facultatif event_type fait envoyer au test un exemple de payload réaliste pour ce type d’événement. Sans lui, le test envoie un payload générique.
Développement local
En développement local, utilisez des outils comme ngrok ou localtunnel pour exposer votre serveur local :
# Start ngrok
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/notifuse
Permissions
Les abonnements sortants suivent la permission Abonnements webhook : lecture liste les abonnements, en ouvre un et affiche son historique de livraisons, avec le payload de chaque événement ainsi que le statut et le corps de la réponse du point d’accès. Écriture crée, met à jour, supprime, active et désactive les abonnements, et déclenche une livraison de test, qui compte comme une écriture parce qu’elle fait appeler votre serveur.
Les appels entrants des fournisseurs suivent la permission Événements webhook : lecture affiche les appels bruts que vos fournisseurs d’email ont renvoyés à Notifuse, avec les adresses des destinataires et les diagnostics des fournisseurs. L’écriture sur Événements webhook ne contrôle rien aujourd’hui : les lignes arrivent par les routes d’appel des fournisseurs, qui n’ont pas de session et ne vérifient aucune permission, donc l’accorder ne donne rien. La console l’affiche accordée et verrouillée.
Le catalogue des types d’événements disponibles ne demande aucune permission : tout membre ou toute clé authentifiés peuvent le lister.
Deux actions restent réservées au propriétaire de l’espace de travail, quelles que soient les permissions d’un membre ou d’une clé API :
- Régénérer le secret de signature d’un abonnement. Le secret est aussi caché à tous sauf au propriétaire, si bien que la lecture sur Abonnements webhook ne l’expose jamais : un membre peut lister les abonnements et inspecter les livraisons sans jamais voir la clé qui signe ces payloads.
- Enregistrer des webhooks auprès d’un fournisseur d’email, car cette action utilise les identifiants du fournisseur stockés dans votre intégration.
Attention
L’écriture sur Abonnements webhook va plus loin que son nom ne le laisse penser. Un abonnement choisit les événements qu’il reçoit : qui détient cette permission peut donc s’abonner aux événements de contact et d’email et faire livrer ces données à l’URL de son choix. Accordez-la comme vous accorderiez la lecture des contacts et de l’historique des messages qui se cachent derrière ces événements.
Remarques
- En production, les webhooks exigent des points d’accès en HTTPS
- Le secret de signature est généré automatiquement à la création d’un abonnement
- Utilisez
webhookSubscriptions.regenerateSecretpour renouveler le secret de signature - Consultez la référence de l’API pour la documentation complète des points d’accès
