Webhooks

Webhooks send real-time notifications to external systems when email events occur. They enable you to integrate Mumara Campaigns with CRMs, analytics platforms, custom applications, and mobile notification services.

Overview

When an email event occurs (delivered, opened, clicked, etc.), webhooks send an HTTP POST request to your specified endpoint or push notification to your device.

EMAIL EVENT                    WEBHOOK                      DESTINATION
      |                            |                             |
      v                            v                             v
+--------------+           +--------------+           +--------------+
| Email opened |   --->    | Match event  |   --->    | POST to URL  |
| by recipient |           | criteria?    |           | or Pushover  |
+--------------+           +--------------+           +--------------+

Use Cases

• CRM Integration - Update contact records when emails are delivered or opened
• Analytics - Track email engagement in external platforms
• Alerts - Get notified of bounces or complaints in real-time
• Custom Apps - Trigger workflows in your own applications
• Mobile Notifications - Receive push alerts for important events

---

Viewing Webhooks

Navigate to Actions → Webhooks to view all webhooks.

Page Features

• Add New button to create a webhook
• Status toggle for each webhook
• Test button to send test data
• Edit and Delete actions

Webhook Information

Column	Description
Name	Webhook name
Endpoint	Destination URL or Pushover
Events	Event types that trigger this webhook
Status	Active or Inactive
Created On	Date and time created
Actions	Edit, Test, Delete

---

Creating a Webhook

Navigate to Actions → Webhooks and click Add New.

Basic Settings

Webhook Name

Enter a descriptive name for the webhook.

Examples:

• "CRM Integration - Opens"
• "Analytics - All Events"
• "Bounce Alerts - Pushover"

Status

Toggle to enable or disable the webhook.

---

Event Criteria

Event Type

Currently, webhooks support Email events.

Event Selection

Select which email events trigger this webhook:

Event	Description
Received	Email received by mail server
Delivered	Email successfully delivered to inbox
Bounced	Email bounced (hard or soft)
Rejected	Email rejected by receiving server
Delayed	Email delayed in queue
Newsletter Opened	Recipient opened a newsletter email
Newsletter Clicked	Recipient clicked a link in newsletter
Transactional Opened	Recipient opened a transactional email
Transactional Clicked	Recipient clicked a link in transactional email
Complaints	Recipient marked email as spam

Event Selection

Select only the events you need. Subscribing to unnecessary events creates extra load on both systems.

---

Optional Filters

Narrow webhook triggers to specific sending infrastructure.

Available Filters

Filter	Description
Sending Domain	Only trigger for specific sending domains
Sending Node	Only trigger for specific SMTP servers
Bridge	Only trigger for specific SMTP credentials
Dedicated IP	Only trigger for specific IP addresses

Filter Configuration

1. Enable the filter by selecting it
2. Choose the specific values to match
3. Multiple values can be selected (OR logic)

Example: Filter webhooks to only fire when emails are sent from your production SMTP server, not your test server.

---

Notification Channels

Web Endpoint

Send HTTP POST requests to a URL.

Settings

Field	Description
Type	Web
Postback URL	HTTPS endpoint to receive webhook data

Requirements

• URL must be publicly accessible
• HTTPS recommended for security
• Endpoint should return 2xx status code
• Endpoint should respond within reasonable time

Payload Format

Webhooks send JSON data. Example payload:

{
  "event": "delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "email": "recipient@example.com",
  "campaign_id": 123,
  "broadcast_name": "January Newsletter",
  "sending_domain": "mail.example.com",
  "sending_node": "smtp1",
  "message_id": "abc123xyz"
}

Pushover Notifications

Send push notifications to mobile devices via Pushover.

Settings

Field	Description
Type	Pushover
User Key	Your Pushover user key
API Token	Your Pushover application token
Sound	Notification sound

Sound Options

Option	Description
Mute	No sound
Vibrate	Vibration only
Pushover	Default Pushover sound
Bike	Bike bell sound
Bugle	Bugle call
Cash Register	Cash register sound
Classical	Classical music
Cosmic	Cosmic sound
Falling	Falling sound
Gamelan	Gamelan instrument
Incoming	Incoming call
Intermission	Intermission sound
Magic	Magic sound
Mechanical	Mechanical sound
Piano Bar	Piano music
Siren	Siren sound
Space Alarm	Space alarm
Tug Boat	Tug boat horn
Alien Alarm	Alien alarm
Climb	Climbing sound
Persistent	Persistent alert
Echo	Echo sound
Up Down	Up-down sound
None	Silent

Setting Up Pushover

1. Create an account at pushover.net
2. Install the Pushover app on your device
3. Copy your User Key from the dashboard
4. Create an application to get an API Token
5. Enter both keys in webhook settings

---

Managing Webhooks

Editing a Webhook

1. Click the Edit button next to a webhook
2. Modify settings as needed
3. Click Save

Testing a Webhook

1. Click the Test button next to a webhook
2. A sample payload is sent to your endpoint
3. Verify you receive the test data

Test Before Production

Always test your webhook endpoint before enabling it for production events.

Deleting a Webhook

1. Click the Delete button next to a webhook
2. Confirm deletion

Changing Status

Toggle the Status switch to enable or disable the webhook.

---

Webhook Limits

Your account may have webhook limits based on your package.

Checking Limits

• View current usage vs. limit in the webhooks list
• Contact administrator if you need additional webhooks

Limit Behavior

• Cannot create webhooks beyond your limit
• Existing webhooks continue to function
• Upgrade package to increase limit

---

Integration Examples

CRM Integration (HubSpot, Salesforce)

Track email engagement in your CRM:

1. Create a webhook endpoint in your CRM or middleware
2. Subscribe to Delivered, Newsletter Opened, Newsletter Clicked events
3. Map payload fields to CRM contact properties
4. Update engagement scores based on events

Analytics Platform (Google Analytics, Mixpanel)

Send engagement data to analytics:

1. Create a server-side endpoint that forwards to analytics
2. Subscribe to Opened and Clicked events
3. Transform payload to analytics event format
4. Track email engagement alongside other metrics

Slack/Teams Notifications

Get alerts for important events:

1. Create an incoming webhook in Slack/Teams
2. Build a middleware that transforms payload to Slack format
3. Subscribe to Bounced and Complaints events
4. Receive instant alerts in your channel

Custom Application

Trigger workflows in your app:

1. Create an API endpoint in your application
2. Subscribe to relevant events
3. Process payload and trigger appropriate actions
4. Return 200 status to acknowledge receipt

---

Best Practices

Endpoint Design

• Use HTTPS - Encrypt data in transit
• Validate payload - Verify data comes from Mumara
• Respond quickly - Return 2xx status promptly
• Handle failures - Implement retry logic on your end
• Log requests - Keep records for debugging

Event Selection

• Be selective - Only subscribe to events you'll use
• Use filters - Narrow to specific domains/nodes when possible
• Consider volume - High-volume events (delivered) generate more requests

Security

• Authenticate requests - Use secret tokens in headers
• Validate origin - Check request comes from expected source
• Limit exposure - Don't expose sensitive operations via webhooks

Reliability

• Idempotent handlers - Handle duplicate events gracefully
• Queue processing - Use a queue for high-volume webhooks
• Monitor errors - Track failed webhook deliveries

---

Troubleshooting

Webhook Not Firing

Possible causes:

• Webhook is inactive
• Event doesn't match criteria
• Filters exclude the event

Solutions:

• Check webhook status is active
• Verify event types are selected
• Review optional filters

Endpoint Not Receiving Data

Possible causes:

• URL is incorrect
• Endpoint is not publicly accessible
• Firewall blocking requests
• SSL certificate issues

Solutions:

• Verify URL is correct and accessible
• Check firewall rules
• Ensure valid SSL certificate
• Test endpoint with curl or Postman

Pushover Not Working

Possible causes:

• Invalid user key or API token
• Pushover app not installed
• Device notifications disabled

Solutions:

• Verify credentials in Pushover dashboard
• Install and configure Pushover app
• Check device notification settings

Missing Events

Possible causes:

• Event type not selected
• Filters too restrictive
• Events occurring outside filter criteria

Solutions:

• Add required event types
• Review and adjust filters
• Test with broader criteria

Duplicate Events

Possible causes:

• Multiple webhooks for same event
• Retry mechanism sending duplicates

Solutions:

• Review webhook configurations
• Implement idempotent handling in your endpoint
• Use message_id for deduplication

---

Payload Reference

Common Fields

All webhook payloads include:

Field	Type	Description
event	string	Event type (delivered, opened, etc.)
timestamp	string	ISO 8601 timestamp
email	string	Recipient email address
message_id	string	Unique message identifier

Event-Specific Fields

Additional fields vary by event type and may include:

Field	Description
campaign_id	Campaign/broadcast ID
broadcast_name	Broadcast name
sending_domain	Domain used for sending
sending_node	SMTP server name
link_url	Clicked link URL (click events)
bounce_type	Bounce classification (bounce events)
complaint_type	Complaint type (complaint events)

---

Next Steps

• Triggers - Create event-based automation rules
• Broadcasts - Create email campaigns for webhook events