Webhooks API

Configure webhooks to receive real-time notifications when emails arrive.

How Webhooks Work

When an email is received, Mailhooks will send a POST request to your configured webhook URL with the email data. This allows you to process emails in real-time without polling the API.

1. Email Received

Email arrives at your domain

2. Webhook Triggered

POST request sent to your URL

3. Process Email

Your app handles the data

Create Webhook

Create a new webhook endpoint.

POST http://localhost:3000/api/v1/webhooks

Request Body

{
  "url": "https://your-app.com/webhook/mailhooks",
  "events": ["email.received"],
  "description": "Production webhook for email processing"
}

Example Request

curl -X POST http://localhost:3000/api/v1/webhooks \
     -H "x-api-key: mh_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.com/webhook/mailhooks",
       "events": ["email.received"]
     }'

Webhook Endpoints

List Webhooks

Get all configured webhooks for your account.

GET http://localhost:3000/api/v1/webhooks

Update Webhook

Update an existing webhook configuration.

PUT http://localhost:3000/api/v1/webhooks/:id

Delete Webhook

Remove a webhook endpoint.

DELETE http://localhost:3000/api/v1/webhooks/:id

Webhook Payload

When an email is received, Mailhooks sends the following payload to your webhook:

{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "em_1234567890",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello from Mailhooks",
    "date": "2024-01-15T10:30:00Z",
    "html": "<html>...</html>",
    "text": "Plain text content...",
    "headers": {
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Hello from Mailhooks",
      "message-id": "<[email protected]>"
    },
    "attachments": [
      {
        "id": "att_0987654321",
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 102400
      }
    ]
  }
}

Webhook Security

Mailhooks signs all webhook requests to verify they're coming from us. The signature is included in the X-Mailhooks-Signature header.

⚠️ Important: Always verify webhook signatures to ensure requests are legitimate and haven't been tampered with.

Verifying Webhook Signatures

// Node.js example
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return hash === signature;
}

// In your webhook handler
app.post('/webhook/mailhooks', (req, res) => {
  const signature = req.headers['x-mailhooks-signature'];
  const isValid = verifyWebhookSignature(
    req.body, 
    signature, 
    process.env.MAILHOOKS_WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook...
});

Retry Policy

If your webhook endpoint doesn't respond with a 2xx status code, Mailhooks will retry the delivery with exponential backoff:

Retry 1

5 seconds

Retry 2

30 seconds

Retry 3

2 minutes

Retry 4

10 minutes

Retry 5

30 minutes

Webhook Logs

View logs for a specific webhook to debug delivery issues.

GET http://localhost:3000/api/v1/webhooks/:id/logs

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`perPage`	integer	Items per page (default: 20)
`status`	string	Filter by status: success, failed

Best Practices

🚀 Respond Quickly

Process webhooks asynchronously and return 200 OK immediately

🔒 Verify Signatures

Always validate webhook signatures before processing

🔄 Handle Duplicates

Use email IDs to prevent processing the same email twice

📊 Monitor Health

Check webhook logs regularly for failed deliveries