Webhooks: Be taught How To Set Up and Monitor Electronic mail Occasions in…

August 29, 2025

Webhooks are a strong solution to obtain real-time notifications when occasions happen in your e mail campaigns. This complete information will educate you what webhooks are, how they work with e mail programs, and the way to implement Mailjet’s webhook performance to trace e mail occasions like opens, clicks, bounces, and extra in actual time.

By the top of this information, you’ll perceive the way to arrange and optimize webhook endpoints, deal with completely different occasion sorts, and implement finest practices for dependable, scalable e mail occasion processing.

What’s a Webhook?

A webhook is a straightforward approach for one system to inform one other that “one thing simply occurred.” It’s an HTTP POST request despatched to a URL you present (your “webhook endpoint”) containing a JSON payload that describes the occasion. Not like APIs that you just ballot on a schedule, webhooks are event-driven as they push knowledge solely when there’s one thing new to report.

Consider webhooks because the web’s model of a telephone name: as a substitute of repeatedly checking if one thing occurred, the system calls you instantly when it does.

Why groups use webhooks

Webhooks supply a number of benefits for e mail advertising and transactional e mail workflows:

• Actual-time notifications: Replace your software the second an e mail is opened or a hyperlink is clicked
• Sooner help and operations: Set off alerts when bounce or block charges spike
• Cleaner knowledge administration: Auto-sync unsubscribes and exhausting bounces to your CRM
• Enhanced personalization: Ship follow-up messages when clients interact (or don’t)
• Higher analytics: Stream occasions into your dashboards or knowledge warehouse

Webhook vs API polling

Understanding the distinction between webhooks and conventional e mail API polling helps illustrate why webhooks are sometimes the higher alternative:

How Mailjet e mail webhooks work

Mailjet can ship webhook notifications for the next e mail occasions:

• despatched: Electronic mail was efficiently despatched
• open: Recipient opened the e-mail
• click on: Recipient clicked a hyperlink within the e mail
• bounce: Electronic mail bounced (delicate or exhausting)
• blocked: Electronic mail was blocked by the recipient’s server
• spam: Electronic mail was marked as spam
• unsub: Recipient unsubscribed

Understanding webhook payloads

Every webhook accommodates a JSON payload with event-specific data. Listed here are examples of frequent occasion sorts:

Open occasion payload

                            

                                {
  "occasion": "open",
  "time": 1433103519,
  "MessageID": 19421777396190490,
  "e mail": "api@mailjet.com",
  "mj_campaign_id": 7173,
  "mj_contact_id": 320,
  "customcampaign": "",
  "CustomID": "helloworld",
  "Payload": "",
  "ip": "127.0.0.1",
  "geo": "US",
  "agent": "Mozilla/5.0 ..."
}
                            
                        

Bounce occasion payload

                            

                                {
  "occasion": "bounce",
  "time": 1430812195,
  "MessageID": 13792286917004336,
  "e mail": "bounce@mailjet.com",
  "blocked": true,
  "hard_bounce": true,
  "error_related_to": "recipient",
  "error": "person unknown"
}

                            
                        

Processing completely different occasion sorts

Every occasion kind requires completely different dealing with methods:

• Unsubscribed/spam: Instantly suppress the contact throughout all programs
• Exhausting bounce: Take away from mailing lists and cease future sends
• Blocked: Examine error particulars and supplier data to diagnose deliverability points
• Click on/open: Set off follow-up campaigns, rating engagement, and personalize buyer journeys

Mailjet webhook finest practices

Following these finest practices ensures dependable webhook processing and optimum efficiency:

Response dealing with

• Return HTTP 200 OK instantly: Acknowledge receipt as shortly as attainable
• Course of asynchronously: Persist the payload to a queue or database, then course of it individually

Reliability and safety

• Use HTTPS: Host your endpoint on a safe connection
• Implement authentication: Shield your endpoint with primary auth or API keys
• Monitor failures: Monitor non-200 responses to forestall URL suspension

Efficiency optimization

• Decrease processing time: Do minimal work within the request handler to keep away from timeouts
• Use occasion grouping: Configure Model=2 to batch a number of occasions in single requests
• Arrange backup URLs: Configure failover endpoints to take care of occasion circulation throughout outages

Retry habits

Mailjet routinely retries failed webhook deliveries for as much as 24 hours in case your endpoint doesn’t return a 200 OK response. If repeated errors persist, the webhook URL could also be suspended. You possibly can configure a backup URL to make sure steady occasion supply.

Organising Mailjet webhooks

You possibly can configure Mailjet webhooks utilizing both the API or the online interface. Listed here are each approaches:

Choice A: API Setup (Really helpful for builders)

This technique provides extra management and is good for automated deployments.

Step 1: Select your occasion sorts

Determine which occasions you wish to observe: despatched, open, click on, bounce, blocked, spam, or unsub.

Step 2: Create the Webhook through API

Use the eventcallbackurl useful resource to configure your webhook:

                            

                                curl -X POST 
  https://api.mailjet.com/v3/REST/eventcallbackurl 
  -H 'Authorization: Primary ' 
  -H 'Content material-Kind: software/json' 
  -d '{
    "EventType": "open",
    "Url": "https://instance.com/webhooks/mailjet/open",
    "Model": 2
  }'

                            
                        

Configuration notes:

• Model=2 allows grouped occasions in a single POST request
• Set “isBackup”: true on a secondary URL to create a failover endpoint

Step 3: Take a look at your integration

Ship a take a look at e mail and carry out the tracked motion (open, click on, and so forth.) to confirm you obtain webhook occasions.

Choice B: Net interface setup (no-code choice)

For groups preferring a visible interface:

1. Log in to app.mailjet.com and navigate to Account Settings
2. Underneath REST API, choose “Occasion notifications (webhooks)”
3. Add one URL for all occasions or outline devoted URLs per occasion kind
4. Take a look at with actual occasions quite than the “Ship take a look at” function, which posts empty payloads

Webhook implementation examples

Listed here are minimal webhook receiver implementations in common programming languages:

Node.js with categorical

                            

                                const categorical = require('categorical');
const app = categorical();

app.use(categorical.json());

app.submit('/webhooks/mailjet/open', (req, res) => {
  // 1. Persist the occasion knowledge shortly
  console.log('Obtained webhook:', req.physique);
  // TODO: Save to queue or database
  // await saveToQueue(req.physique);

  // 2. Acknowledge instantly
  res.standing(200).ship('okay');
});

app.pay attention(3000, () => {
  console.log('Webhook server working on port 3000');
});

                            
                        

Python with flask

                            

                                from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/mailjet/open', strategies=['POST'])
def handle_open_event():
    knowledge = request.get_json()

    # Course of the webhook knowledge
    print(f"Obtained webhook: {knowledge}")
    # TODO: Save to queue or database
    # save_to_queue(knowledge)

    return jsonify({"standing": "okay"}), 200

if __name__ == '__main__':
    app.run(port=3000)
                            
                        

Superior configuration suggestions

Listed here are some suggestions that can assist you get much more from webhooks.

Batch processing at scale

Use Model=2 in your webhook configuration to cut back HTTP overhead by receiving a number of occasions in batched requests:

                            

                                {
  "EventType": "open",
  "Url": "https://instance.com/webhooks/mailjet/batch",
  "Model": 2
}
                            
                        

Occasion correlation and monitoring

Use CustomID and EventPayload parameters in your Ship API calls to make webhook occasions simpler to correlate along with your inner programs:

                            

                                {
  "Messages": [{
    "To": [{"Email": "user@example.com"}],
    "Topic": "Welcome!",
    "TextPart": "Welcome to our service!",
    "CustomID": "user-123-welcome",
    "EventPayload": "marketing campaign=onboarding&phase=new_users"
  }]
}

                            
                        

Enterprise-scale occasion streaming

For top-volume functions, take into account streaming occasions to third-party queue companies:

• Azure Service Bus
• Amazon SQS
• Google Cloud Pub/Sub

Ceaselessly requested questions

What occasions does Mailjet ship to webhooks?

Mailjet sends despatched, open, click on, bounce, blocked, spam, and unsub occasions. Every accommodates the MessageID, contact and marketing campaign identifiers, and event-specific particulars (comparable to url for click on occasions).

How briskly are occasions delivered?

Occasions are pushed shortly after they happen, sometimes inside seconds. In case your endpoint doesn’t reply with HTTP 200 OK, Mailjet retries supply for as much as 24 hours.

Can I cut back the variety of webhook calls?

Sure. Configure grouped supply by setting Model=2 in your eventcallbackurl so Mailjet batches a number of occasions in a single POST request.

How do I safe my webhook endpoint?

Use HTTPS, defend the endpoint with primary authentication, and limit entry by IP filtering or API gateways. All the time course of payloads server-side and by no means expose webhook endpoints to shopper functions.

Fast setup guidelines

Observe this guidelines to implement Mailjet webhooks efficiently:

• [ ] Create and safe a public HTTPS endpoint
• [ ] Configure eventcallbackurl through API or internet interface
• [ ] Implement fast HTTP 200 OK responses with asynchronous processing
• [ ] Add CustomID and EventPayload to your e mail sends for simpler correlation
• [ ] Monitor webhook failures and configure backup URLs
• [ ] Arrange occasion streaming to your analytics or alerting programs

Subsequent steps and extra sources

Now that you just perceive webhook fundamentals and implementation, take into account exploring these associated Mailjet options:

Abstract

Webhooks present a strong, environment friendly solution to obtain real-time notifications about e mail occasions. By implementing Mailjet webhooks with correct error dealing with, safety measures, and asynchronous processing, you may construct responsive, data-driven e mail workflows that improve buyer expertise and enhance operational effectivity.

Bear in mind to begin easy, monitor your implementation intently, and scale your webhook processing as your e mail quantity grows. With the inspiration supplied on this information, you’re able to harness the total energy of real-time e mail occasion monitoring.

Writer:
The Sinch Mailjet Staff

The staff at Sinch Mailjet