How to Setup Maileroo Webhooks?

Integrating Maileroo webhooks into your system is a powerful way to keep track of your email events in real time. Webhooks are automated messages sent from apps when something happens. In the case of Maileroo, these hooks can notify you about various email events. Here’s a guide on setting up Maileroo webhooks effectively.

Understanding Maileroo Webhook Events

Maileroo webhooks can notify you about several types of email events. The global event types include:

Knowing which event type has occurred can help you respond appropriately. For instance, tracking 'delivered' and 'opened' can help you understand your email engagement better. We introduce more event types in the future.

Setting Up Maileroo Webhooks

In order to use Maileroo webhook system, please go through the following steps:

1. Go to the Maileroo Dashboard: The first step is to log in to your Maileroo Dashboard. This is where you can manage all aspects of your Maileroo integration. Click on Events section.
2. Add a Callback URL: In the dashboard, look for the webhook settings. Here, you'll add the URL where you want Maileroo to send notifications. This URL is your listener endpoint which will receive webhook events.

3. Use the Shared Secret: Maileroo provides a shared secret for securing communications. This secret is used to generate a signature for each webhook event, ensuring the data you receive is legitimate and hasn’t been tampered with.

Understanding Webhook Payloads

Maileroo webhook payloads are sent in JSON format. They contain detailed information about each event, including:

• Event Type: Indicates the type of email event (e.g., delivered, opened).
• Message Details: Includes IDs, timestamps, email addresses, and other relevant data.

Here are examples of what Maileroo webhook payloads look like:

{
  "domain_id": 123,
  "event_data": {
    "to": "recipient@example.com"
  },
  "event_id": "abcd1234efgh5678ijkl9101",
  "event_time": 1710545542,
  "event_type": "delivered",
  "inserted_at": "2024-03-15T23:32:22.397Z",
  "message_id": "<1234567890abcdef@examplemail.com>",
  "message_reference_id": "mref1234567890abcdef",
  "tags": null,
  "user_id": 1001
}

{
  "domain_id": 456,
  "event_data": {
    "from": ["sender@examplemail.com"],
    "to": ["receiver@examplemail.com"]
  },
  "event_id": "mnop1234qrst5678uvwx9101",
  "event_time": 1710545560,
  "event_type": "accepted",
  "inserted_at": "2024-03-15T23:32:40.441Z",
  "message_id": "<0987654321fedcba@examplemail.com>",
  "message_reference_id": "mref0987654321fedcba",
  "tags": null,
  "user_id": 1002
}

{
  "domain_id": 789,
  "event_data": {
    "ip": "123.45.67.89",
    "user_agent": "Mozilla/5.0 (Compatible; ExampleBrowser/1.0; Windows NT)"
  },
  "event_id": "ghij1234klmn5678opqr9101",
  "event_time": 1710545567,
  "event_type": "opened",
  "inserted_at": "2024-03-15T23:32:47.664Z",
  "message_id": "<abcdef1234567890@examplemail.com>",
  "message_reference_id": "mrefabcdef1234567890",
  "tags": null,
  "user_id": 1003
}

{
  "domain_id": 123,
  "event_data": {
    "reason": "452-4.2.2 The recipient's inbox is out of storage space. Please direct the recipient to support link.",
    "to": "example@email.com"
  },
  "event_id": "0dc2204928b817f0122d1e311aee0ee702ac378840ef7df5",
  "event_time": 1710545557,
  "event_type": "deferred",
  "inserted_at": "2024-03-15T23:32:37.427Z",
  "message_id": "<312897663424678224496834.5399.202431411321@domain.com>",
  "message_reference_id": "982e548d6b5ff15562272aa42b1f4517",
  "tags": null,
  "user_id": 123
}

{
  "domain_id": 774,
  "event_data": {
    "ip": "103.120.6.123",
    "original_url": "https://example.com/confirm/link",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0"
  },
  "event_id": "cb91d71458a75cb7160a2cca9c472a42a97bf925385998e0",
  "event_time": 1710545577,
  "event_type": "clicked",
  "inserted_at": "2024-03-15T23:32:57.401Z",
  "message_id": "<499840827041934075286474.8057.2024315233239@domain.com>",
  "message_reference_id": "0ed7094bf9509ac3145c4aa97182be44",
  "tags": null,
  "user_id": 323
}

Each payload comes with an x-maileroo-signature header, which you should verify using the shared secret to ensure the payload’s integrity.

The webhook payload is signed using HMAC-SHA256. The payload itself is used as the data, and a shared secret key, provided by Maileroo, is used for generating the signature. This method ensures that the receiver can verify the authenticity and integrity of the received data, thereby safeguarding against tampering or interception.

Reattempt Mechanism

When a webhook fails to deliver its payload successfully, Maileroo employs a reattempt mechanism based on the number of previous attempts made. This mechanism is designed to retry sending the webhook payload at progressively increasing intervals, thereby giving the receiving server time to recover from any transient issues.

Here's how the reattempt mechanism works:

1. First Attempt: If the first attempt to send a webhook fails, Maileroo schedules the next attempt for 5 minutes later (300 seconds from the current time).
2. Subsequent Attempts: If further attempts are needed, the interval before the next attempt increases progressively:
   • The second attempt is scheduled for 10 minutes (600 seconds) later.
   • The third for 15 minutes (900 seconds) later.
   • This pattern continues, increasing the delay to 30 minutes, 1 hour, 2 hours, 4 hours, and finally 6 hours for the eighth attempt.
3. Stopping the Reattempts: If the webhook has not been successfully delivered after eight attempts, the reattempt mechanism stops, and no further attempts are made.
4. Successful Delivery: It's important to note that if at any point the webhook is successfully delivered (indicated by a 200 status code response), the reattempt process is terminated immediately.

Best Practices for Handling Webhooks

• Secure Your Endpoint: Ensure that the endpoint you expose for receiving webhooks is secure and can handle the anticipated volume of webhook calls.
• Verify Signatures: Always verify the x-maileroo-signature to ensure the authenticity of the data received.
• Log and Monitor: Keep logs of the webhook events received for troubleshooting and analysis.

By following these steps, you can effectively set up and manage Maileroo webhooks, allowing for real-time monitoring and response to your email system events. This setup not only enhances your email management but also provides valuable insights into your email interactions.