Webhooks
Prévenu quand cela se produit, pas quand vous demandez.
Enregistrez un endpoint https et recevez un POST signé quand du courrier arrive, part, est rejeté ou est ouvert.
En bref
Qu’est-ce qu’un webhook e-mail ?
Un webhook est une requête HTTP qu’un service envoie à votre URL quand quelque chose se produit, pour que votre code réagisse au lieu d’interroger en boucle. Pour l’e-mail, c’est du courrier qui arrive, part, est rejeté ou est ouvert.
20
événements auxquels s’abonner
10
endpoints par boîte mail
5
tentatives par événement au maximum
100
échecs d’affilée désactivent un endpoint
Comment ça marche
Toutes les façons d’envoyer, un événement
L’éditeur, un envoi programmé pour mardi et l’API déclenchent tous email.sent. La programmation déclenche d’abord email.scheduled.
Signé, et à vous de vérifier
Chaque POST porte un HMAC-SHA-256 de l’horodatage et du corps brut. Vérifiez les octets tels qu’ils sont arrivés et refusez tout ce qui date de plus de 300 secondes.
Retenté seulement si cela peut marcher
Les délais dépassés, 408, 425, 429 et 5xx sont retentés après 1, 5 et 25 minutes, puis 2 heures. Tout autre 4xx est définitif, et 410 désactive l’endpoint.
Vingt événements en trois familles
N’en choisir aucun abonne à tous les événements de message sauf email.replied.
Vérifier une remise
Le SDK vérifie le HMAC en temps constant et refuse les remises de plus de cinq minutes.
import { verifyWebhookSignature } from '@openemail/sdk' export default async (request: Request) => { const event = await verifyWebhookSignature({ payload: await request.text(), headers: request.headers, secret: process.env.OPENEMAIL_WEBHOOK_SECRET! }) console.log(event.type, event.data) return new Response(null, { status: 204 })}Ce que vous obtenez
Déjà dans le produit
Cinq secondes, en parallèle
Les endpoints sont appelés en même temps, donc dix prennent toujours cinq secondes.
Uniquement en https public
Les hôtes privés et de bouclage sont refusés, et une redirection n’est jamais suivie.
Chaque tentative journalisée
Chacune montre ce que votre serveur a répondu et en combien de temps.
Bonnes pratiques
En tirer le meilleur parti
- 01
Répondre, puis travailler
Renvoyez un 2xx en moins de cinq secondes et faites le travail lent ensuite.
- 02
Écarter les id répétés
Stockez chaque id X-OpenEmail-Delivery traité et ignorez les répétitions.
- 03
Renouveler avec les deux secrets
Le renouvellement remplace le secret aussitôt : vérifiez avec l’ancien et le nouveau jusqu’à ce que votre déploiement soit en ligne.
Questions
On nous demande souvent
Pour aller plus loin
Fonctionne bien avec
Commencer
Votre domaine,
votre courrier.
Pointez un domaine vers OpenEmail et lisez son courrier dans une boîte mail pensée pour lui. Le forfait gratuit couvre un domaine.
