Getting started with webhooks

What is a webhook ?

Webhooks are widely used nowadays as they are key to allowing multiple systems to interconnect and keep actions consistent among them. They're also known as "URL Callbacks" or "HTTP push calls".

When an event or status change occurs in a system, an HTTP POST request is sent to the given URL in real time. This POST call contains information related to that specific event. E.g Time it occured, name of the event, key identifiers.

In order for webhooks to work, you will need to define a notification URL or endpoint on your side where the event data will be pushed in behalf of Brevo whenever it's triggered.

Webhooks in Brevo

There're multiple types of events you can track in Brevo. You can for instance receive notifications on the status of your ongoing marketing campaign and know how it's performing in real time. You could also track when your transactional messages are being sent, delivered or opened by your recipients. Or you can also be notified about any changes on your contact lists.

To make these use cases easier to address we have grouped all the available events in 2 categories: Marketing and Transactional Events. You can see the list of events covered for each category here:

• Marketing Events
• Transactional Events

Limits for webhook creation

The number of webhook creation (marketing + transactional) is limited to a maximum of 40. If you already have more than 40 webhooks, you will not be allowed to create more until you delete some of the existing webhooks to bring the total count upto 40.

Setting up your first webhook

For this example we will focus on the delivered event from the transactional platform. Basically, whenever we send a new e-mail we will receive a notification via our webhook indicating the e-mail has successfully hit the recipient's inbox.


Keep in mind there's multiple transactional events you can track via webhooks:
Sent , Delivered, Opened, Clicked, Soft Bounce, Hard Bounce, Invalid Email, Deferred, Complaint, Unsubscribed, Blocked, Error.
You can do the full overview here

📘

Managing Webhooks

You can also do these actions straight from the API, if you prefer. The endpoints that will help you are Create a webhook and Update a webhook in case you want to change the webhook definition.

2. We chose to track the delivered event in the previous step. Brevo will post the event specific data to your URL every time a transactional email is delivered to the recipient's inbox. Let's send another email:

curl --request POST \
  --url https://api.brevo.com/v3/smtp/email \
  --header 'accept: application/json' \
  --header 'api-key: xkeysib-xxxxxxxxxxx' \
  --header 'content-type: application/json' \
  --data '{
  "sender":{"email":"[email protected]"},
  "to":[{"email":"[email protected]"}],
  "replyTo":{"email":"[email protected]"},
  "textContent":"This is a transactional email",
  "subject":"Subject Line",
  "tags":["myFirstTransactional"]
  }'

📘

Pro Tip

When sending a transactional email you can also pass the tags object to specify a custom flag or identifier which could help you query through the received events on your side.

3. Once our message is delivered the following data will be posted to your URL. You can expect the same structure every time an event of the same kind is triggered.

{
  "event": "delivered",
  "email": "[email protected]",
  "id": 26224,
  "date": "YYYY-MM-DD HH:mm:ss",
  "ts": 1598634509,
  "message-id": "<[email protected]>",
  "ts_event": 1598034509,
  "subject": "Subject Line",
  "tag": "[\"transactionalTag\"]",
  "sending_ip": "185.41.28.109",
  "ts_epoch": 1598634509223,
  "tags": [
    "myFirstTransactional"
  ]
}

Securing your webhooks

Once you have tested your notify URL properly receives webhook notifications from Brevo , you might want to make sure it's not accessible in the web to other parties. To achieve this you need to apply a whitelist rule to Brevo's IP addresses :

📘

Brevo Webhook IP's

The outgoing webhook requests from Brevo will be sent from the following CIDR IP ranges:

• 1.179.112.0/20

This means you will need to whitelist the whole IP address range:

First IP address: 1.179.112.1
Last IP address: 1.179.127.254

*Please note that these IP ranges relate to marketing webhooks , transactional webhooks, and webhooks called directly from the automation platform.

👍

You're all set, congrats!

You can go ahead and start exploring all the events you can track in the next guides.