Webhooks

Webhooks allow MoMail to notify your application in real-time when events occur, such as receiving a new email.

List Webhooks

Retrieve all configured webhooks.

GET /webhooks

Response

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://api.yourapp.com/webhooks/momail",
      "events": ["email.received", "email.processed"],
      "secret": "whsec_****",
      "active": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Create Webhook

Configure a new webhook endpoint.

POST /webhooks

Request Body

{
  "url": "https://api.yourapp.com/webhooks/momail",
  "events": ["email.received", "email.processed"],
  "secret": "your_webhook_secret"
}

Parameters

Field	Type	Required	Description
url	string	Yes	HTTPS URL to receive webhook payloads
events	array	Yes	List of events to subscribe to
secret	string	No	Secret for verifying webhook signatures

Supported Events

Event	Description
email.received	New email received
email.processed	Email processing completed
domain.verified	Domain verification successful
api_key.created	New API key created

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://api.yourapp.com/webhooks/momail",
    "events": ["email.received", "email.processed"],
    "secret": "whsec_****",
    "active": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Get Webhook

Retrieve details for a specific webhook.

GET /webhooks/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	Webhook UUID

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://api.yourapp.com/webhooks/momail",
    "events": ["email.received"],
    "active": true,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastDelivered": "2024-01-15T14:22:00.000Z",
    "deliveryStats": {
      "success": 150,
      "failure": 2
    }
  }
}

Update Webhook

Modify an existing webhook configuration.

PUT /webhooks/{id}

Request Body

{
  "url": "https://api.yourapp.com/webhooks/momail",
  "events": ["email.received", "email.processed", "domain.verified"],
  "secret": "new_webhook_secret"
}

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://api.yourapp.com/webhooks/momail",
    "events": ["email.received", "email.processed", "domain.verified"],
    "active": true
  }
}

Delete Webhook

Remove a webhook configuration.

DELETE /webhooks/{id}

Response

{
  "success": true,
  "data": {
    "message": "Webhook deleted successfully"
  }
}

Webhook Payloads

Email Received

{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "email_id": "msg_abc123",
    "message_id": "<message-id@sender.com>",
    "subject": "Project Update",
    "from": "sender@example.com",
    "to": ["recipient@yourdomain.com"],
    "date": "2024-01-15T10:29:55.000Z",
    "mailbox_id": "mb_xyz789",
    "domain": "yourdomain.com",
    "has_attachments": true,
    "thread_id": "thread_123"
  }
}

Verifying Webhooks

MoMail signs webhook payloads using your webhook secret. Verify the signature to ensure the webhook came from MoMail.

Signature Header

X-Webhook-Signature: sha256={signature}

Verification Example

JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

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

// Express.js example
app.post('/webhooks/momail', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhook(payload, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Received event:', req.body.event);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib
from flask import request, abort

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/momail', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature', '').replace('sha256=', '')
    payload = request.get_data(as_text=True)
    secret = os.environ['WEBHOOK_SECRET']

    if not verify_webhook(payload, signature, secret):
        abort(401)

    data = request.get_json()
    print(f"Received event: {data['event']}")
    return 'OK', 200

Retry Policy

If your endpoint returns a non-2xx status code, MoMail will retry:

Attempt	Delay
1	Immediate
2	5 seconds
3	25 seconds

After 3 failed attempts, the webhook is marked as failing and must be manually reactivated.

Code Examples

cURL

# Create webhook
curl -X POST https://api.momail.io/v1/webhooks \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/momail",
    "events": ["email.received"],
    "secret": "whsec_your_secret"
  }'

# List webhooks
curl https://api.momail.io/v1/webhooks \
  -H "X-API-Key: your_key"

# Delete webhook
curl -X DELETE https://api.momail.io/v1/webhooks/wh_abc123 \
  -H "X-API-Key: your_key"