Webhooks

Recevez des notifications en temps réel via webhooks

Introduction

Les webhooks permettent à JunkMail d'envoyer des notifications HTTP à votre serveur lorsque certains événements se produisent.

Événements disponibles

Événement	Description
email.received	Un nouvel email a été reçu
email.deleted	Un email a été supprimé
address.created	Une nouvelle adresse a été créée
address.expired	Une adresse a expiré
address.deleted	Une adresse a été supprimée

Configurer un webhook

POST /api/v1/webhooks

Scope requis : webhooks:manage

Corps de la requête

Champ	Type	Requis	Description
url	string	Oui	URL de votre endpoint
events	string[]	Oui	Liste des événements
secret	string	Non	Secret pour la signature (généré si omis)

Exemple

curl -X POST https://api.junkmail.dev/api/v1/webhooks \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-site.com/webhooks/junkmail",
    "events": ["email.received", "address.expired"]
  }'

Réponse

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://votre-site.com/webhooks/junkmail",
    "events": ["email.received", "address.expired"],
    "secret": "whsec_xxxxxxxxxxxx",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Important : Le secret n'est affiché qu'une seule fois. Conservez-le précieusement.

---

Format des notifications

JunkMail envoie une requête POST à votre URL avec le payload suivant :

Headers

Content-Type: application/json
X-JunkMail-Signature: sha256=xxxxxxxx
X-JunkMail-Event: email.received
X-JunkMail-Delivery-ID: del_123abc

Payload

{
  "id": "evt_456def",
  "type": "email.received",
  "createdAt": "2024-01-16T14:30:00Z",
  "data": {
    "emailId": "email_789ghi",
    "addressId": "addr_123abc",
    "from": "noreply@example.com",
    "subject": "Confirmation de votre inscription",
    "receivedAt": "2024-01-16T14:30:00Z"
  }
}

---

Vérifier la signature

Pour sécuriser votre endpoint, vérifiez la signature de chaque requête.

Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Dans votre handler
app.post('/webhooks/junkmail', (req, res) => {
  const signature = req.headers['x-junkmail-signature'];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Traiter l'événement...
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

---

Retries

Si votre endpoint ne répond pas avec un code 2xx, JunkMail réessaie :

Tentative	Délai
1	Immédiat
2	1 minute
3	5 minutes
4	30 minutes
5	2 heures

Après 5 échecs, le webhook est désactivé automatiquement.

---

Gérer les webhooks

Lister les webhooks

GET /api/v1/webhooks

Supprimer un webhook

DELETE /api/v1/webhooks/:id