Configurer les webhooks

Published: 16 juillet 2026 · Last updated: 21 juillet 2026 · By Marcus Biel

Les webhooks permettent à Maildroppa de notifier une autre application lorsqu'un événement important se produit dans votre compte.

Au lieu de demander continuellement à Maildroppa si un abonné a été créé, mis à jour, désabonné ou associé à un tag, votre application peut recevoir une requête HTTPS peu après l'événement.

La page Webhooks est l'emplacement central de cette intégration à l'échelle du compte. Vous pouvez créer plusieurs endpoints, choisir les événements que chaque endpoint reçoit, ajouter des en-têtes d'authentification, tester la connexion, consulter les tentatives de livraison et relancer un événement de production si nécessaire.

Fonctionnement des webhooks de compte

Un webhook de compte suit le processus suivant :

1. Un événement se produit dans Maildroppa, par exemple la création d'un abonné.
2. Maildroppa recherche chaque endpoint actif abonné à cet événement.
3. Maildroppa crée une livraison pour chaque endpoint correspondant.
4. La charge utile JSON est signée avec le secret de signature des webhooks de votre compte.
5. Maildroppa envoie une requête HTTPS POST à l'URL d'endpoint enregistrée.
6. Votre endpoint vérifie la signature, stocke ou traite l'événement et renvoie une réponse HTTP.
7. Maildroppa enregistre le résultat dans l'historique des livraisons et réessaie automatiquement les échecs temporaires.

Si plusieurs endpoints sont abonnés au même événement, chaque endpoint reçoit sa propre livraison. L'événement métier possède le même Event ID pour tous, tandis que chaque livraison possède son propre Delivery ID.

Les webhooks de compte diffèrent d'une étape « Envoyer un webhook » dans une Automation. Les webhooks de compte écoutent les événements sélectionnés du compte dans Maildroppa. Un webhook d'Automation est envoyé uniquement lorsqu'un abonné atteint cette étape précise. Les deux utilisent le secret de signature des webhooks du compte ; la rotation du secret affecte donc tous les récepteurs de webhooks sortants qui vérifient les signatures Maildroppa.

Ouvrir la page Webhooks

Ouvrez « Settings », développez « Developers » et sélectionnez « Webhooks ».

La page contient trois zones principales :

• Secret de signature
• Endpoints
• Historique des livraisons pour l'endpoint sélectionné

Lorsque vous avez plusieurs endpoints, sélectionnez une ligne d'endpoint pour afficher son historique des livraisons. Si vous n'en avez pas sélectionné explicitement, Maildroppa affiche l'historique du premier endpoint de la liste.

Avant de créer un endpoint

Préparez un récepteur sur votre serveur avant de configurer Maildroppa. Le récepteur doit :

• Être accessible via une URL HTTPS publique.
• Accepter les requêtes POST avec un corps application/json.
• Conserver le corps brut de la requête jusqu'à la vérification de la signature Maildroppa.
• Renvoyer un statut 2xx uniquement après avoir accepté l'événement de manière sécurisée.
• Traiter les livraisons répétées de manière idempotente en utilisant l'Event ID.
• Répondre rapidement au lieu d'effectuer un traitement lent pendant la requête.

Une méthode fiable consiste à vérifier la requête, à stocker l'Event ID et la charge utile dans une file d'attente durable ou une base de données, à renvoyer 200 ou 204, puis à traiter l'action métier.

N'exposez pas un ordinateur de développement, une adresse de réseau local ou un script non protégé comme récepteur de webhook en production. Maildroppa accepte uniquement les cibles HTTPS publiques et vérifie à nouveau la destination lors de l'envoi d'une livraison.

Étape 1 : générer le secret de signature

Chaque requête webhook Maildroppa est signée. Votre récepteur utilise le secret de signature pour vérifier que la requête a été créée par Maildroppa et que le corps n'a pas été modifié pendant le transport.

En haut de la page, le panneau Secret de signature affiche l'un des états suivants :

• Missing — Aucun secret de signature n'existe encore.
• Ready — Un secret de signature est configuré.
• Loading — Maildroppa récupère l'état actuel.

Cliquez sur « Generate secret » lorsque l'état est Missing.

Maildroppa affiche immédiatement le nouveau secret. Il commence par whsec_. Cliquez sur « Copy » et stockez-le dans le gestionnaire de secrets ou dans la configuration d'environnement protégée utilisée par votre récepteur.

La valeur complète n'est affichée qu'immédiatement après sa génération ou sa rotation. Lorsque vous rechargez la page ou la quittez, Maildroppa indique seulement qu'un secret existe et quand il a été mis à jour pour la dernière fois. Le secret enregistré ne vous est pas révélé à nouveau.

Si vous perdez le secret

Si le récepteur ne possède plus le secret actuel, cliquez sur « Rotate secret » et enregistrez la nouvelle valeur affichée.

La rotation remplace immédiatement le secret précédent. Maildroppa ne conserve pas les deux valeurs pendant une période de transition. Mettez à jour tous les récepteurs qui utilisent ce secret de compte avant d'envoyer d'autres tests ou de vous fier aux livraisons de production.

Les nouvelles livraisons, les nouvelles tentatives planifiées, les tests et les relances sont signés avec le secret actuel au moment de la requête HTTP. Ainsi, une livraison créée avant la rotation peut tout de même être signée avec le nouveau secret lorsqu'elle est tentée ultérieurement.

Traiter le secret comme un mot de passe

Ne placez pas le secret de signature dans du code exécuté dans le navigateur, un dépôt public, une URL, une page d'erreur ou un journal d'application ordinaire.

Seul le récepteur côté serveur a besoin du secret. Si vous pensez qu'il a été exposé, faites-le tourner et mettez immédiatement à jour tous les récepteurs.

Vérifier la signature d'un webhook

Chaque requête contient les en-têtes Maildroppa suivants :

• X-Maildroppa-Event-Id — Identifie l'événement métier.
• X-Maildroppa-Delivery-Id — Identifie cette livraison particulière.
• X-Maildroppa-Timestamp — Heure de signature en secondes Unix.
• X-Maildroppa-Signature — Signature HMAC versionnée.

Maildroppa envoie également :

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

La signature suit ce format :

v1=<lowercase hexadecimal HMAC>

Maildroppa la crée avec HMAC-SHA256. Le contenu signé est l'horodatage, suivi d'un point, puis du corps JSON brut exact de la requête :

<timestamp>.<raw request body>

Utilisez le secret de signature comme clé HMAC.

L'exemple Node.js suivant présente l'étape essentielle de vérification. rawBody doit correspondre aux octets originaux de la requête, et non à du JSON déjà analysé puis sérialisé à nouveau.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Après avoir vérifié la signature, comparez également l'horodatage avec l'heure de votre serveur. Rejetez les requêtes qui dépassent une courte tolérance définie pour votre infrastructure, par exemple cinq minutes. Cela réduit le risque qu'une requête valide interceptée soit relancée beaucoup plus tard.

N'analysez et ne traitez le JSON qu'après la réussite de ces deux vérifications.

Causes courantes des erreurs de signature

Une signature échoue généralement pour l'une des raisons suivantes :

• Le récepteur utilise un ancien secret après une rotation.
• Un middleware a analysé ou modifié le JSON avant le calcul de la signature.
• Le récepteur signe uniquement le corps et omet <timestamp>..
• L'horodatage est traité comme une date formatée au lieu d'utiliser la valeur exacte de l'en-tête.
• Le préfixe v1= est omis lors de la comparaison.
• Le HMAC calculé est encodé différemment au lieu d'être en hexadécimal minuscule.

Consignez l'Event ID et le Delivery ID lorsque la vérification échoue, mais ne consignez jamais le secret de signature ni les valeurs sensibles des en-têtes personnalisés.

Étape 2 : ajouter un endpoint

Cliquez sur « Add endpoint » dans la section Endpoints.

L'éditeur comprend quatre parties :

• URL de l'endpoint
• Événements
• En-têtes personnalisés
• État actif

Les nouveaux endpoints sont actifs par défaut et tous les événements affichés dans l'éditeur sont initialement sélectionnés. Vérifiez la sélection avant l'enregistrement afin que le récepteur ne reçoive que les notifications dont il a réellement besoin.

Configurer l'URL de l'endpoint

Saisissez l'URL publique complète qui doit recevoir les requêtes Maildroppa, par exemple :

https://integrations.example.com/webhooks/maildroppa

L'URL doit respecter les exigences suivantes :

• Elle doit utiliser https://.
• Elle doit contenir un nom d'hôte public valide.
• Elle peut comporter jusqu'à 2 048 caractères.
• Elle ne peut pas contenir de variables de modèle avec { ou }.
• Elle ne peut pas contenir de nom d'utilisateur ni de mot de passe avant le nom d'hôte.
• Elle ne peut pas contenir de fragment d'URL commençant par #.
• Elle doit utiliser le port HTTPS standard 443.
• Elle ne peut pas utiliser localhost, une adresse IP brute ni un nom d'hôte qui se résout vers un réseau privé ou réservé bloqué.

Les paramètres de requête sont pris en charge, mais ne placez pas de clés API ni d'autres secrets dans l'URL. Les URL sont visibles dans la liste des endpoints et les données de livraison. Utilisez plutôt un en-tête personnalisé pour les identifiants.

Maildroppa ne suit pas les redirections. Enregistrez la destination HTTPS finale plutôt qu'une URL qui renvoie 301, 302, 307 ou 308.

Le nom d'hôte de destination est résolu à nouveau avant l'envoi. Un nom d'hôte qui se résout ultérieurement vers une adresse privée ou bloquée est rejeté, même s'il était valide lors de l'enregistrement de l'endpoint.

Choisir les événements

Sélectionnez au moins un événement. Un endpoint reçoit uniquement les types d'événements sélectionnés dans son éditeur.

La page propose les choix d'événements suivants :

Subscriber Created — subscriber.created

Envoyé lorsqu'un abonné est créé dans le compte Maildroppa.

Utilisez cet événement pour créer le contact correspondant dans un CRM, une plateforme de données client, une base de données interne ou un autre système tenant compte des autorisations.

N'interprétez pas cet événement comme la preuve que chaque inscription a terminé le Double Opt-in. Le statut de l'abonné dans la charge utile décrit son état actuel.

Subscriber Updated — subscriber.updated

Envoyé lorsque les informations intégrées de l'abonné ou les valeurs des champs personnalisés changent.

Utilisez l'objet abonné complet de la charge utile comme représentation actuelle dans Maildroppa. Évitez de supposer qu'une seule propriété particulière a changé.

Les associations et suppressions de tags ont leurs propres types d'événements afin de pouvoir être traitées séparément.

Subscriber Unsubscribed — subscriber.unsubscribed

Envoyé lorsque l'abonné passe à l'état désabonné à la suite d'une action de désabonnement.

Utilisez cet événement pour supprimer le contact des systèmes connectés. Ne réabonnez pas automatiquement la personne parce qu'un autre système indique encore que le contact est actif.

Tag Added — subscriber.tag_added

Envoyé lorsqu'un tag est associé à un abonné.

La charge utile contient l'abonné et le tag concernés par cette modification précise.

Tag Removed — subscriber.tag_removed

Envoyé lorsqu'un tag est supprimé d'un abonné.

La charge utile contient l'abonné mis à jour et le tag supprimé. Le tag supprimé est fourni séparément, même s'il ne figure plus dans le tableau tags actuel de l'abonné.

Form Submitted — form.submitted

Envoyé lorsqu'un visiteur envoie un formulaire d'inscription Maildroppa.

Considérez-le comme un signal d'envoi de formulaire, et non comme la confirmation que le Double Opt-in est terminé. Tout workflow nécessitant une inscription confirmée doit continuer à respecter le statut actuel de l'abonné et le processus de confirmation.

Utiliser des endpoints distincts lorsque les responsabilités diffèrent

Vous pouvez envoyer différents événements à différents systèmes. Par exemple :

• Envoyer les événements d'abonné et de tag à un CRM.
• Envoyer les événements de désabonnement à un service de suppression.
• Envoyer les événements d'envoi de formulaire à un pipeline d'analyse.

Des endpoints distincts réduisent le trafic inutile et facilitent le diagnostic des échecs. Chaque endpoint possède sa propre sélection d'événements, son URL, ses en-têtes personnalisés, son état actif, ses tests et son historique des livraisons.

Ajouter des en-têtes personnalisés

Les en-têtes personnalisés sont facultatifs. Utilisez-les lorsque le récepteur exige une clé API, un jeton bearer, un identifiant de locataire ou un autre en-tête fixe.

Cliquez sur « Add header », puis saisissez le nom et la valeur de l'en-tête. Voici des exemples appropriés :

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Vous pouvez ajouter jusqu'à 20 en-têtes personnalisés.

Noms des en-têtes :

• Ils sont obligatoires.
• Ils peuvent comporter jusqu'à 128 caractères.
• Ils doivent utiliser des caractères valides pour un nom d'en-tête HTTP.
• Ils doivent être uniques sans distinction entre majuscules et minuscules.

Valeurs des en-têtes :

• Elles sont obligatoires.
• Elles peuvent comporter jusqu'à 2 000 caractères.
• Elles ne peuvent pas contenir de sauts de ligne.

Les noms suivants sont réservés et ne peuvent pas être remplacés par un en-tête personnalisé :

• Content-Type
• Content-Length
• Host
• User-Agent
• Tout nom commençant par X-Maildroppa-

Cela empêche une valeur personnalisée de remplacer les en-têtes de livraison et de signature de Maildroppa.

Stockage des secrets des en-têtes

Maildroppa chiffre les valeurs des en-têtes personnalisés avant de les stocker. Les valeurs enregistrées ne sont pas renvoyées au navigateur sous une forme lisible.

Lorsque vous modifiez l'endpoint ultérieurement, le champ de valeur affiche « Stored value kept ». Laissez-le vide lorsque le secret existant doit rester inchangé. Saisissez une nouvelle valeur pour le remplacer.

Si vous modifiez le nom de l'en-tête, saisissez à nouveau la valeur. Maildroppa ne conserve un secret enregistré que tant que son nom d'en-tête d'origine reste inchangé.

La suppression d'une ligne d'en-tête supprime cet en-tête des futures livraisons après l'enregistrement de l'endpoint.

Les valeurs des en-têtes personnalisés sont considérées comme sensibles dans les informations de requête stockées. Elles sont masquées plutôt qu'affichées dans l'historique des livraisons.

Définir l'endpoint comme actif ou inactif

Laissez « Active » sélectionné lorsque l'endpoint est prêt à recevoir immédiatement des événements.

Désélectionnez-le lorsque vous souhaitez enregistrer la configuration sans commencer les livraisons. Vous pourrez activer l'endpoint ultérieurement depuis la liste des endpoints.

Un endpoint inactif :

• Ne reçoit pas les nouveaux événements.
• Ne peut pas envoyer de webhook de test.
• Reste visible et modifiable.
• Conserve son historique des livraisons existant.

L'activation d'un endpoint ne récupère pas les événements survenus pendant sa période d'inactivité.

Cliquez sur « Save » lorsque l'URL, la sélection des événements, les en-têtes et l'état sont corrects.

Comprendre la liste des endpoints

Chaque ligne d'endpoint affiche :

• L'URL de destination.
• Un badge Active ou Inactive.
• Les types d'événements suivis.
• Le nombre d'en-têtes personnalisés.
• La date de dernière mise à jour de l'endpoint.

Les actions disponibles sont les suivantes :

• On/Off — Active ou désactive l'endpoint.
• Test — Envoie une requête de test immédiate à un endpoint actif.
• Edit — Modifie l'URL, les événements, les en-têtes ou l'état actif.
• Delete — Supprime définitivement la configuration de l'endpoint après confirmation.

Sélectionnez la partie principale d'une ligne pour ouvrir l'historique des livraisons de cet endpoint sous la liste.

Impact des modifications enregistrées sur les livraisons existantes

Un événement de compte crée une livraison avec un instantané de l'URL de l'endpoint, de la charge utile et des en-têtes personnalisés à ce moment-là.

La modification de l'URL ou des en-têtes personnalisés affecte les livraisons nouvellement créées. Une livraison déjà en file d'attente conserve sa destination et sa configuration d'en-têtes enregistrées d'origine.

La modification des événements sélectionnés n'affecte également que les événements qui se produisent ensuite. Maildroppa ne crée pas rétroactivement de livraisons pour les types d'événements qui n'étaient pas sélectionnés au moment de l'événement.

Le secret de signature est différent : il est lu lors de la préparation de la requête HTTP. Une livraison en attente ou une relance peut donc utiliser un nouveau secret de signature ayant fait l'objet d'une rotation, même si sa charge utile et son instantané d'endpoint ont été créés auparavant.

Tester un endpoint

Cliquez sur « Test » sur un endpoint actif une fois le récepteur et le secret de signature prêts.

Maildroppa envoie immédiatement une requête signée en utilisant l'URL d'endpoint enregistrée et les en-têtes personnalisés enregistrés. Les modifications non enregistrées dans un éditeur ouvert ne sont pas incluses dans le test.

La charge utile de test utilise le type d'événement webhook.test et définit livemode sur false :

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Les ID générés et l'horodatage diffèrent pour chaque test réel.

Un test effectue exactement une tentative HTTP. Les livraisons de test ne sont pas placées dans le calendrier de nouvelles tentatives de production et ne peuvent pas être relancées.

Une fois la requête terminée, le panneau de résultat affiche :

• Test success ou Test failed
• Event ID
• Statut HTTP, lorsqu'une réponse a été reçue
• Durée
• Delivery ID
• Informations sur l'erreur, le cas échéant
• Extrait de la réponse, lorsque le récepteur a renvoyé un corps

Le test apparaît également dans l'historique des livraisons avec un badge Test. Utilisez le filtre « Test » pour n'afficher que les requêtes de test.

Comprendre la charge utile de production

Les événements de compte de production utilisent une enveloppe JSON commune :

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Les propriétés de niveau supérieur signifient :

• id — L'Event ID. Il correspond à X-Maildroppa-Event-Id.
• type — La clé d'événement sélectionnée dans l'éditeur de l'endpoint.
• schema_version — La version du schéma de la charge utile. Utilisez-la pour déterminer comment analyser l'événement.
• created_at — L'heure de création de la charge utile, en UTC.
• livemode — true pour les événements de production et false pour les événements de test.
• data — Le contenu propre à l'événement.

Acheminez les événements selon la valeur exacte de type. Ignorez les propriétés supplémentaires dont votre intégration n'a pas besoin afin que l'ajout de propriétés compatibles ne rompe pas le récepteur.

Charge utile des événements d'abonné

Les événements d'abonné contiennent la représentation actuelle de l'abonné dans data.subscriber :

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields et tags sont des tableaux. Ils peuvent être vides. Une propriété d'abonné peut également être null lorsqu'aucune valeur n'existe ; votre récepteur doit donc suivre le schéma de la charge utile au lieu de supposer que chaque valeur de profil facultative est présente.

Charge utile des événements de tag

Les événements de tag contiennent à la fois l'abonné et le tag à l'origine de l'événement :

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Pour subscriber.tag_removed, data.tag identifie toujours le tag supprimé, même si le tableau tags actuel de l'abonné ne le contient plus.

Event IDs, Delivery IDs et idempotence

L'Event ID et le Delivery ID ont des fonctions différentes.

Event ID

L'Event ID identifie l'événement métier. Il apparaît dans :

• La propriété id de niveau supérieur de la charge utile.
• L'en-tête de requête X-Maildroppa-Event-Id.
• L'historique des livraisons.

Le même événement peut être envoyé à plusieurs endpoints abonnés. Ces livraisons partagent l'Event ID.

Les nouvelles tentatives et les relances manuelles conservent également l'Event ID d'origine. Stockez les Event IDs traités et rendez l'action métier idempotente afin qu'une requête répétée ne crée pas de contacts en double, ne répète pas une action irréversible et n'applique pas deux fois la même modification.

Delivery ID

Le Delivery ID identifie un enregistrement de livraison. Il apparaît dans :

• L'en-tête de requête X-Maildroppa-Delivery-Id.
• L'historique des livraisons.

Chaque livraison d'endpoint possède son propre Delivery ID. Une relance manuelle crée un nouveau Delivery ID tout en conservant l'Event ID d'origine.

Utilisez le Delivery ID pour le traçage technique et le support. Utilisez l'Event ID pour la déduplication au niveau métier.

Renvoyer la réponse HTTP appropriée

Maildroppa classe les réponses comme suit :

• Toute réponse 2xx marque la livraison comme réussie.
• Les réponses 408 Request Timeout, 429 Too Many Requests et 5xx sont des échecs temporaires et peuvent faire l'objet de nouvelles tentatives.
• Les échecs réseau susceptibles d'être temporaires font l'objet de nouvelles tentatives.
• Les redirections et autres réponses 3xx ne sont pas suivies et sont considérées comme des échecs définitifs.
• Les autres réponses 4xx sont considérées comme des échecs définitifs et ne font pas l'objet de nouvelles tentatives.

Renvoyez 200, 202 ou 204 uniquement lorsque l'événement a été accepté de manière sécurisée. Si le traitement prend du temps, stockez d'abord l'événement et renvoyez une réponse de réussite avant d'effectuer le traitement lent de manière asynchrone.

Ne renvoyez pas de redirection vers une autre URL de webhook. Configurez plutôt l'URL finale dans Maildroppa.

Calendrier des nouvelles tentatives automatiques

Les livraisons de production peuvent effectuer jusqu'à sept tentatives HTTP.

Après un échec pouvant faire l'objet d'une nouvelle tentative, Maildroppa planifie la tentative suivante selon les délais suivants :

1. Après la tentative 1 : 1 minute
2. Après la tentative 2 : 5 minutes
3. Après la tentative 3 : 30 minutes
4. Après la tentative 4 : 2 heures
5. Après la tentative 5 : 12 heures
6. Après la tentative 6 : 24 heures

Si la tentative 7 reçoit encore un échec pouvant faire l'objet d'une nouvelle tentative, la livraison devient Dead et aucune autre tentative automatique n'est planifiée.

Le calendrier est calculé à partir de chaque tentative ayant échoué. L'heure réelle de livraison peut être légèrement décalée, car les livraisons sont traitées de manière asynchrone et soumises à des limites de protection du système.

Corrigez si possible le problème temporaire du récepteur avant l'heure « Next retry » affichée. Si les tentatives automatiques sont terminées, utilisez Replay une fois le récepteur à nouveau opérationnel.

Comprendre l'historique des livraisons

L'historique des livraisons correspond à l'endpoint actuellement sélectionné. L'URL de l'endpoint apparaît dans l'en-tête de la section afin que vous puissiez confirmer l'historique consulté.

Utilisez les filtres suivants :

• All — Affiche les livraisons de production et de test.
• Production — Affiche uniquement les livraisons d'événements réels.
• Test — Affiche uniquement les tests manuels.

Cliquez sur « Refresh » pour récupérer l'état le plus récent. Il n'est pas nécessaire de laisser l'historique ouvert pendant que Maildroppa envoie ou réessaie une livraison.

La page affiche les 50 dernières livraisons correspondant au filtre sélectionné.

Colonnes des livraisons

Chaque ligne contient :

• Created — Date de création de l'enregistrement de livraison.
• State — Pending, Success, Failed ou Dead.
• HTTP — Statut de réponse, nombre de tentatives, durée et heure de la prochaine tentative, le cas échéant.
• Subscriber — E-mail de l'abonné lorsque l'événement est associé à un abonné.
• Delivery — Type d'événement, Event ID et Delivery ID.
• Actions — Replay lorsque la livraison peut être relancée.

Si aucune requête HTTP n'a été effectuée, la colonne HTTP affiche « No HTTP attempt ». Cela peut se produire lorsque Maildroppa rejette la requête avant l'envoi, par exemple si le secret de signature est manquant ou si la destination enregistrée ne peut plus être utilisée de manière sûre.

Lorsqu'elles sont disponibles, la ligne affiche également une erreur et un extrait de réponse renvoyé par le récepteur. Ne renvoyez pas de secrets ni de données personnelles sensibles dans le corps de la réponse d'un webhook, car une partie de cette réponse peut apparaître dans le journal des livraisons du compte.

États des livraisons

Pending signifie que la livraison attend sa première tentative ou une nouvelle tentative planifiée. « Next retry » apparaît lorsqu'une autre tentative a été planifiée.

Success signifie que le récepteur a renvoyé une réponse 2xx. Aucune autre tentative automatique n'est nécessaire.

Failed signifie que la livraison s'est terminée en raison d'un problème ne permettant pas de nouvelle tentative, a été rejetée avant toute tentative HTTP ou a été arrêtée avant de pouvoir être envoyée.

Dead signifie que toutes les tentatives automatiques prévues pour un problème pouvant faire l'objet d'une nouvelle tentative ont été utilisées sans recevoir de réponse réussie.

Conservation de l'historique

Les enregistrements de livraison sont conservés pendant une durée limitée :

• Livraisons de production réussies : 30 jours
• Livraisons de production échouées : 90 jours
• Livraisons de production Dead : 90 jours
• Livraisons de test : 30 jours

Conservez vos propres journaux d'intégration si vous avez besoin d'un historique d'audit plus long. Stockez les Event IDs et les Delivery IDs, mais évitez de stocker inutilement les secrets.

Relancer une livraison

Cliquez sur « Replay » lorsqu'une livraison de production terminée doit être tentée à nouveau.

Replay est disponible pour les livraisons de production dans l'état Success, Failed ou Dead. Il n'est pas disponible lorsqu'une livraison est Pending, et les livraisons de test ne peuvent pas être relancées.

Une relance :

• Crée une nouvelle livraison Pending.
• Crée un nouveau Delivery ID.
• Conserve l'Event ID d'origine.
• Conserve le type d'événement et la charge utile JSON d'origine.
• Utilise l'instantané d'origine de l'URL cible et des en-têtes personnalisés.
• Utilise le secret de signature actuel lors de la préparation de la nouvelle requête.

La relance ne reconstruit pas la charge utile à partir des données actuelles de l'abonné. Elle renvoie l'instantané de l'événement d'origine. Cela rend la relance auditable et empêche un événement historique de changer de signification sans que vous le sachiez.

Une seule relance de la même livraison source peut être Pending à la fois. Attendez la fin de cette relance avant d'en demander une autre.

Assurez-vous que l'endpoint est actif avant de le relancer. Si l'endpoint est inactif, la relance en file d'attente ne peut pas être livrée correctement.

Comme un récepteur peut avoir terminé l'action métier même lorsque Maildroppa n'a pas reçu sa réponse de réussite, une relance peut produire une requête en double. La déduplication par Event ID protège le système connecté contre la répétition de l'action.

Modifier un endpoint

Cliquez sur « Edit » pour modifier l'URL, la sélection d'événements, les en-têtes personnalisés ou l'état actif.

Avant l'enregistrement :

1. Vérifiez que la nouvelle URL est déjà disponible.
2. Laissez les valeurs d'en-têtes enregistrées vides lorsqu'elles doivent rester inchangées.
3. Saisissez une nouvelle valeur pour chaque en-tête renommé.
4. Vérifiez la sélection des événements afin de ne pas supprimer accidentellement les notifications nécessaires.
5. Enregistrez et envoyez un nouveau webhook de test.

N'oubliez pas que les livraisons en file d'attente conservent leur URL et leur instantané d'en-têtes personnalisés existants. Testez la nouvelle configuration pour les livraisons futures au lieu de supposer qu'elle modifie une ancienne requête en file d'attente.

Désactiver un endpoint

Utilisez le bouton On/Off lorsque vous souhaitez mettre une intégration en pause sans supprimer sa configuration ni son historique.

Lorsqu'un endpoint est désactivé :

• Les nouveaux événements ne sont plus mis en file d'attente pour cet endpoint.
• Les livraisons Pending qui n'ont pas encore été prises en charge pour l'envoi sont marquées Failed.
• Test est désactivé.
• L'endpoint reste disponible pour être modifié et réactivé ultérieurement.

Une requête déjà en cours au moment de la désactivation peut tout de même se terminer. Consultez l'historique des livraisons après avoir désactivé l'endpoint si cette distinction est importante pour votre intégration.

Les événements manqués pendant l'inactivité de l'endpoint ne sont pas récupérés lorsque vous le réactivez.

Supprimer un endpoint

Cliquez sur « Delete » et confirmez l'avertissement lorsque l'endpoint ne doit plus exister.

La suppression retire l'endpoint de la page, arrête les futures livraisons d'événements et fait échouer les livraisons Pending qui n'avaient pas encore été prises en charge pour l'envoi.

Delete ne sert pas à effectuer une pause temporaire. Utilisez le bouton On/Off lorsque vous pourriez avoir besoin de la configuration ou de son historique visible ultérieurement.

Avant la suppression, notez les Event IDs ou Delivery IDs dont vous avez encore besoin pour l'audit de votre intégration.

Dépannage

Impossible d'enregistrer l'endpoint

Vérifiez que :

• L'URL commence par https://.
• L'URL utilise un nom d'hôte public et le port 443.
• L'URL ne contient ni variables, ni informations de connexion, ni fragment.
• Au moins un événement est sélectionné.
• Chaque en-tête personnalisé possède un nom unique et une valeur.
• Les en-têtes Maildroppa et HTTP réservés ne sont pas utilisés comme noms personnalisés.

Test désactivé

Test n'est disponible que pour un endpoint actif. Activez l'endpoint ou modifiez-le et sélectionnez « Active », puis enregistrez avant de tester.

Le test n'affiche aucune tentative HTTP

Générez un secret de signature si l'état est Missing. Vérifiez également que le nom d'hôte de destination est public et se résout toujours correctement.

Une requête peut être rejetée avant l'envoi lorsque son secret, son URL, ses en-têtes personnalisés ou le contrôle de sécurité de sa destination n'est pas valide.

Le récepteur renvoie 401 ou 403

Vérifiez le nom et l'identifiant de l'en-tête personnalisé enregistré. Modifiez l'endpoint et saisissez à nouveau la valeur si elle a changé.

Vérifiez également que le récepteur ne confond pas son propre identifiant d'API avec la signature Maildroppa. Un en-tête d'autorisation personnalisé et X-Maildroppa-Signature ont des fonctions différentes et peuvent être vérifiés indépendamment.

Le récepteur renvoie une redirection

Maildroppa ne suit pas les redirections. Remplacez l'URL de l'endpoint par l'URL HTTPS publique finale et testez à nouveau.

La signature ne correspond pas

Vérifiez que le récepteur :

• Utilise le secret de signature actuel.
• Utilise la valeur exacte de X-Maildroppa-Timestamp.
• Signe <timestamp>.<raw request body>.
• Utilise HMAC-SHA256 et une sortie hexadécimale minuscule.
• Compare la valeur complète, y compris v1=.
• Effectue la comparaison avant que l'analyse JSON ne modifie le corps.

Le même événement arrive plusieurs fois

Cela peut se produire après une interruption réseau, une nouvelle tentative ou une relance manuelle. Il est normal que les systèmes de livraison de webhooks garantissent une livraison au moins une fois plutôt qu'une livraison exactement une fois.

Utilisez l'Event ID comme clé d'idempotence. Renvoyez une réponse 2xx lorsqu'un Event ID déjà traité est reçu à nouveau et qu'aucune action supplémentaire n'est nécessaire.

Une livraison est Pending

Consultez « Next retry » dans la colonne HTTP. Une erreur 408, 429, 5xx pouvant faire l'objet d'une nouvelle tentative, ou un échec réseau temporaire, reste Pending jusqu'à la prochaine tentative planifiée.

Cliquez sur « Refresh » après l'heure de nouvelle tentative pour charger l'état le plus récent.

Une livraison est Dead

Toutes les tentatives automatiques ont été utilisées. Corrigez d'abord le récepteur, assurez-vous que l'endpoint est actif, envoyez un webhook de test, puis utilisez Replay sur la livraison de production.

Checklist de production recommandée

Avant de vous fier à un endpoint en production, vérifiez tous les points suivants :

1. Le récepteur utilise une URL HTTPS publique stable avec un certificat valide.
2. Le secret de signature est stocké en dehors du code source.
3. La signature est vérifiée par rapport au corps brut non modifié.
4. Les anciens horodatages sont rejetés selon une tolérance documentée.
5. Le récepteur stocke et déduplique les Event IDs.
6. Le récepteur consigne les Event IDs et les Delivery IDs pour le traçage.
7. Le traitement lent intervient après l'acceptation durable de l'événement.
8. Une réponse 2xx est renvoyée uniquement pour les événements acceptés.
9. Les identifiants personnalisés sont stockés dans les en-têtes plutôt que dans l'URL.
10. Seuls les types d'événements nécessaires sont sélectionnés.
11. Un webhook de test réussit et apparaît correctement dans l'historique des livraisons.
12. La surveillance vous alerte lorsque les livraisons de production commencent à renvoyer des erreurs.

Avec ces mesures de protection, la page Webhooks fournit les deux éléments d'une intégration fiable : une livraison sécurisée des événements à votre application et un historique opérationnel clair dans Maildroppa.