How to use 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 Sendinblue whenever it's triggered.



Webhooks in Sendinblue

There're multiple types of events you can track in Sendinblue. 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:



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

transactional webhooks pagetransactional webhooks page

transactional webhooks page

📘

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.



  1. We chose to track the delivered event in the previous step. Sendinblue 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.sendinblue.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.



  1. 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 Sendinblue , 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 Sendinblue's IP addresses :

📘

Sendinblue Webhook IP's

The outgoing webhook requests from Sendinblue will be sent from the following CIDR IP range:

185.107.232.0/24

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

First IP address: 185.107.232.0
Last IP address: 185.107.232.255

Please note that these IP ranges relate only to marketing and transactional webhooks.. If you're using webhooks that will be called from inside our marketing automation workflows, the following additional IPs will also need to be whitelisted.




👍

You're all set, congrats!

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


Did this page help you?