Webhooks

Receive real-time notifications via webhooks

Introduction

Webhooks allow JunkMail to send HTTP notifications to your server when certain events occur.

sequenceDiagram
    participant S as Sender
    participant J as JunkMail
    participant C as Your Server
    S->>J: Sends an email
    J->>J: Saves the email
    J->>C: POST /your-webhook (Event: email.received)
    C-->>J: 200 OK
    Note right of J: Notification received in real time!

Available Events

Event	Description
email.received	A new email has been received
email.deleted	An email has been deleted
address.created	A new address has been created
address.expired	An address has expired
address.deleted	An address has been deleted

Configure a Webhook

POST /api/v1/webhooks

Required scope: webhooks:manage

Request Body

Field	Type	Required	Description
url	string	Yes	Your endpoint URL
events	string[]	Yes	List of events (max 10)
secret	string	No	Secret for signature (generated if omitted)

Example

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"]
  }'

Response

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "url": "https://votre-site.com/webhooks/junkmail",
    "events": ["email.received", "address.expired"],
    "secret": "whsec_xxxxxxxxxxxx",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Important: The secret is displayed only once. Store it securely.

---

Notification Format

JunkMail sends a POST request to your URL with the following payload:

Headers

Content-Type: application/json
X-JunkMail-Signature: sha256=xxxxxxxx
X-JunkMail-Timestamp: 1705415400000

Payload

{
  "event": "email.received",
  "timestamp": 1705415400000,
  "data": {
    "emailId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "addressId": "550e8400-e29b-41d4-a716-446655440000",
    "from": "noreply@example.com",
    "subject": "Confirmation de votre inscription",
    "receivedAt": "2024-01-16T14:30:00Z"
  }
}

---

Verify the Signature

To secure your endpoint, verify the signature of each request.

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)
  );
}

// In your 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');
  }

  // Process the event...
  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

If your endpoint does not respond with a 2xx code, JunkMail retries:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failures, the webhook is automatically disabled.

---

Manage Webhooks

List Webhooks

GET /api/v1/webhooks

Required scope: webhooks:manage

Delete a Webhook

DELETE /api/v1/webhooks/:id

Required scope: webhooks:manage

Response

{
  "message": "Webhook deleted successfully"
}