Webhooks

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

List Webhooks

Retrieve all configured webhooks.

GET /v1/api/webhooks

Response

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

Create Webhook

Configure a new webhook endpoint.

POST /v1/api/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
`api_key.created`	New API key created (not emitted yet)

Response

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

The full secret is returned only on create (and when you rotate via PATCH with a new secret). List responses include secret_masked only.

Get Webhook

Retrieve details for a specific webhook.

GET /v1/api/webhooks/{id}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Webhook UUID

Response

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

Update Webhook

Modify an existing webhook configuration.

PATCH /v1/api/webhooks/{id}

Request Body

All fields are optional.

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

Response

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

When secret is updated, the response includes the new full secret once.

Delete Webhook

Remove a webhook configuration.

DELETE /v1/api/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": "<[email protected]>",
    "subject": "Project Update",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "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-MoMail-Signature: sha256={hex_signature}

The signature is HMAC-SHA256 of the raw JSON request body using your webhook secret.

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 header = req.headers['x-momail-signature'] || '';
  const signature = header.replace(/^sha256=/, '');
  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');
});

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-MoMail-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	500 ms
3	1000 ms

Failed deliveries are logged; the webhook remains active until you disable or delete it in the dashboard.

Code Examples

cURL

# Create webhook
curl -X POST https://momail.io/v1/api/webhooks \
  -H "Authorization: Bearer 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://momail.io/v1/api/webhooks \
  -H "Authorization: Bearer your_key"

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