Aller au contenu

Des webhooks e-mail que vous pouvez vérifier, relancer et rejouer.

Sachez quand un e-mail est distribué, rebondit ou suscite une plainte, avec des événements auxquels votre endpoint peut se fier et qu'il ne manque pas en silence.

  • Pas de carte pour tester
  • Prix en euros, hors TVA
verify.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(request, rawBody, secret) {
    const id = request.headers["outstamp-id"];
    const timestamp = request.headers["outstamp-timestamp"];
    const header = request.headers["outstamp-signature"] ?? "";

    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

    const expected = createHmac("sha256", secret)
        .update(`${id}.${timestamp}.${rawBody}`)
        .digest("hex");

    return header.split(",")
        .map((part) => part.trim().replace(/^v1=/, ""))
        .some((candidate) => candidate.length === expected.length &&
            timingSafeEqual(Buffer.from(candidate, "hex"), Buffer.from(expected, "hex")));
}

Ce que contient chaque livraison.

  • Une signature sur le corps brut

    Outstamp-Signature: v1= est un HMAC-SHA256 de l'identifiant de livraison, de l'horodatage et du corps exact. Rejetez tout ce qui date de plus de 5 minutes.

  • Des relances pendant 48 heures

    10 tentatives : immédiatement, puis après 5 secondes, 1, 5 et 30 minutes, et 2, 6, 12, 24 et 48 heures.

  • Un rejeu pendant 30 jours

    Rejouez n'importe quel événement depuis le tableau de bord ou l'API. Il reçoit un nouvel identifiant de livraison et garde son identifiant d'événement.

  • Une rotation sans interruption

    Quand vous renouvelez le secret, l'ancienne et la nouvelle signature sont envoyées pendant 24 heures.

Les événements auxquels vous pouvez vous abonner.

Les événements auxquels vous pouvez vous abonner.
GroupeÉvénementsUsage typique
Distributionemail.sent, email.delivered, email.delivery_delayedMarquer un message comme distribué dans votre application
Problèmesemail.bounced, email.complained, email.rejected, email.failed, email.suppressedArrêter d'écrire à une adresse, ou alerter le support
Cycle de vieemail.accepted, email.scheduled, email.queued, email.canceled, email.submission_unknownPistes d'audit et envois planifiés
Domainesdomain.created, domain.status_changed, domain.deletedSavoir quand le DNS casse
Projetsuppression.created, suppression.deleted, project.quota_warning, project.reputation_warning, project.sending_paused, project.sending_resumedAlertes opérationnelles

Prévoyez ceci avant de développer.

Ce sont les règles de tout système de webhooks honnête.

  • La livraison se fait au moins une fois : dédupliquez sur l'id de l'événement.
  • L'ordre n'est pas garanti : email.delivered peut arriver avant email.sent.
  • Répondez avec n'importe quel 2xx dans les 10 secondes, et faites le travail ensuite.
  • Après 20 échecs consécutifs, l'endpoint est désactivé, et une réponse 410 le désactive immédiatement.

Recevez votre premier événement.

  1. 1

    Ajoutez un endpoint

    Une URL HTTPS publique et les types d'événements voulus. Le secret de signature ne s'affiche qu'une fois.

  2. 2

    Vérifiez la signature

    Utilisez le corps brut, comparez en temps constant et rejetez les horodatages anciens.

  3. 3

    Déclenchez un événement de test

    Envoyez à [email protected] avec une clé de test, ou utilisez le bouton de test du tableau de bord.

Questions sur les webhooks.

Les webhooks sont-ils signés ?

Oui. Chaque livraison porte Outstamp-Signature: v1=, un HMAC-SHA256 de l'identifiant de livraison, de l'horodatage et du corps brut.

Et si mon endpoint est en panne ?

Nous réessayons 10 fois sur 48 heures. Après 20 échecs consécutifs, l'endpoint est désactivé, et vous pouvez rejouer ce qu'il a manqué pendant 30 jours.

Les e-mails de test déclenchent-ils des webhooks ?

Oui. Les envois de test produisent les mêmes événements et webhooks qu'en production, marqués test.

Recevez votre premier événement signé dès aujourd'hui.

Les clés de test et le simulateur sont gratuits, sans carte.

  • Pas de carte pour tester
  • Prix en euros, hors TVA