Receiving Emails

​

1. Create a Webhook Endpoint

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/email', methods=['POST'])
def email_webhook():
    # Get the webhook payload
    data = request.json        
    
    # Process the incoming email
    print(f"Received email: {data['subject']} from {data['sender_address']}")
    
    # Access specific parts of the email
    email_id = data.get('email_id')
    subject = data.get('subject')
    sender = data.get('sender_address')
    recipient = data.get('recipient_address')
    timestamp = data.get('timestamp')
    raw_email = data.get('raw_email_data')
    
    # Your logic here
    # ...
    
    # Return a success response
    return jsonify({"status": "success"}), 200

if __name__ == '__main__':
    app.run(debug=True, port=5000)

​

2. Expose Your Local Webhook Endpoint

ngrok http 3000

1. Find the forwarding URL in the ngrok output:
   Copy

   Ask AI

   Forwarding https://0fcbcda91e79.ngrok.app -> http://localhost:3000
   

2. Create the full webhook URL by appending your webhook endpoint path:
   Copy

   Ask AI

   https://0fcbcda91e79.ngrok.app/webhook/email
   

3. Use this complete URL in the A1Mail dashboard webhook settings.

​

3. Register Your Webhook in the Dashboard

1. Log in to your A1Base Dashboard
2. Navigate to the Email Settings section
3. Find your email address and click “Configure Webhook”
4. Enter your full webhook URL (e.g., https://0fcbcda91e79.ngrok.app/webhook/email)
5. Click “Save Changes”

​

Webhook Precedence

1. Individual email address webhook
2. Custom domain webhook
3. Default webhook

​

4. Test Your Webhook

​

Webhook Payload

{
    "email_id": "a82b3e6b-dc79-46ad-9284-a166629592e3",
    "subject": "Email Subject",
    "sender_address": "[email protected]",
    "recipient_address": "[email protected]",
    "timestamp": "2025-03-19T10:24:08.46083+00:00",
    "service": "email",
    "raw_email_data": "Full email content including headers and body"
}

​

Payload Fields

​

Verifying Signatures on Email Webhooks

​

How it Works

1. Timestamping: Each webhook request includes an x-timestamp header containing the Unix timestamp (in seconds) of when the request was created. This helps protect against replay attacks.
2. Signature Creation: We create a signature string by concatenating the timestamp and the raw JSON body of the request.
   Copy

   Ask AI

   message_to_sign = <timestamp_from_header> + <raw_request_body>
   

3. HMAC-SHA256: This string is then signed using the HMAC-SHA256 algorithm with your company_id as the secret key.
4. Header Inclusion: The resulting signature is sent in the x-signature header of the request.

​

Verification Steps

1. Extract Headers: From the incoming webhook request, extract the x-timestamp and x-signature headers.
2. Check the Timestamp: To mitigate replay attacks, we recommend checking if the x-timestamp is recent (e.g., within the last 5 minutes). If the timestamp is too old, you may choose to reject the request.
3. Prepare the Signature String: Recreate the message_to_sign by concatenating the value from the x-timestamp header with the complete, raw body of the POST request.

   Important: It is critical to use the raw, unmodified request body. Any parsing or modification of the JSON before creating the signature string will result in a mismatch.

4. Generate Your Expected Signature: Using your company_id as the secret key, compute the HMAC-SHA256 hash of the message_to_sign you just created. The output should be a hex-encoded string.
5. Compare Signatures: Compare the x-signature from the request header with your generated signature. If they match exactly, the webhook is authentic and can be trusted. If they do not match, the request should be discarded.

​

Example (Python)

import hmac
import hashlib
import json

def verify_webhook_signature(request_body_raw, headers, company_id):
    """
    Verifies the signature of an incoming email webhook.

    Args:
        request_body_raw (bytes): The raw, unparsed body of the request.
        headers (dict): A dictionary of the request headers.
        company_id (str): Your unique company ID, used as the secret key.

    Returns:
        bool: True if the signature is valid, False otherwise.
    """
    received_timestamp = headers.get('x-timestamp')
    received_signature = headers.get('x-signature')

    if not received_timestamp or not received_signature:
        # Necessary headers are missing
        return False

    # 1. Prepare the message string
    message_to_sign = received_timestamp.encode('utf-8') + request_body_raw

    # 2. Generate the expected signature
    expected_signature = hmac.new(
        key=company_id.encode('utf-8'),
        msg=message_to_sign,
        digestmod=hashlib.sha256
    ).hexdigest()

    # 3. Compare signatures securely
    return hmac.compare_digest(expected_signature, received_signature)

# --- Usage Example ---
# Assuming 'request' is your web framework's request object

# company_id = "your_company_id_goes_here" 
# headers = request.headers
# raw_body = request.get_data() # Use a method that gets the raw body

# is_valid = verify_webhook_signature(raw_body, headers, company_id)

# if is_valid:
#     print("✅ Signature is valid. Processing webhook.")
#     # ... process the webhook payload ...
# else:
#     print("❌ Invalid signature. Discarding request.")

​

Example Raw Email Data

• DKIM signatures
• Message ID
• Content type
• Email body (plain text and HTML versions)
• Custom headers