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

  1. Webhook Triggered

POST request sent to your URL

  1. Process Email

Your app handles the data

Create Webhook

Create a new webhook endpoint.

POSThttps://mailhooks.dev/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 https://mailhooks.dev/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.

GEThttps://mailhooks.dev/api/v1/webhooks

Update Webhook

Update an existing webhook configuration.

PUThttps://mailhooks.dev/api/v1/webhooks/:id

Delete Webhook

Remove a webhook endpoint.

DELETEhttps://mailhooks.dev/api/v1/webhooks/:id

Webhook Payload

When an email is received, Mailhooks sends the following payload to your webhook. If you use custom storage (BYOB), additional fields like storagePath are included so you can fetch the email and attachments from your bucket.

{
  "id": "em_1234567890",
  "from": "sender@example.com",
  "to": ["recipient@yourdomain.com"],
  "subject": "Hello from Mailhooks",
  "body": "Plain text content of the email...",
  "html": "<html><body>HTML content...</body></html>",
  "receivedAt": "2024-01-15T10:30:00Z",
  "headers": {
    "from": "sender@example.com",
    "to": "recipient@yourdomain.com",
    "subject": "Hello from Mailhooks",
    "message-id": "<unique-id@example.com>",
    "date": "Mon, 15 Jan 2024 10:30:00 +0000"
  },
  "attachments": [
    {
      "id": "att_abc123def456",
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 102400,
      "storagePath": "attachments/yourdomain.com/em_1234567890-abc123/document.pdf"
    }
  ],
  "spfResult": "pass",
  "dkimResult": "pass",
  "dmarcResult": "pass",
  "authSummary": "pass",
  "usesCustomStorage": true,
  "storagePath": "emails/em_1234567890/email.eml",
  "storageConfig": {
    "provider": "S3",
    "bucket": "my-email-bucket"
  }
}

Payload Fields

Field

Type

Description

id

string

Unique email ID

from

string

Sender email address

to

string[]

Recipient email addresses

subject

string

Email subject line

body

string

Plain text content

html

string?

HTML content (if available)

receivedAt

string

ISO 8601 timestamp when email was received

headers

object

All email headers as key-value pairs

attachments

array

List of attachments with id, filename, contentType, size, and storagePath (for custom storage)

spfResult

string?

SPF authentication result

dkimResult

string?

DKIM authentication result

dmarcResult

string?

DMARC authentication result

authSummary

string?

Summary of all authentication results

usesCustomStorage

boolean

Whether email is stored in your custom S3 bucket (BYOB)

storagePath

string?

Storage path for the EML file (only present when usesCustomStorage is true)

storageConfig

object?

Storage provider details with provider (S3, AZURE_BLOB, GCS) and bucket name (only present when usesCustomStorage is true)

HTTP Headers

Mailhooks includes the following headers with each webhook request:

Header

Description

Content-Type

application/json

X-Webhook-Signature

HMAC-SHA256 signature of the payload

X-Email-ID

The email ID for reference

Webhook Security

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

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-webhook-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. Each log entry includes the emailId for correlation with the original email.

GEThttps://mailhooks.dev/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