How to Enable Webhooks for Transactional Emails

A webhook is a mechanism for receiving notifications about certain events. You can set up notifications about email deliverability and subscriber activity.

How to Create a Webhook

To connect SMTP Webhooks go to the "Account Settings" section in the "API" tab and click "Create webhook."

Activate SMTP email tracking if you have it disabled.

Specify the URL of your handler where you send events, and mark which events you want to send.

List of events triggered by a webhook in the SMTP service regarding sending emails:

• delivered;
• not delivered;
• open;
• following a link;
• reported as spam;
• unsubscribed

Send Data Format

When a webhook is triggered, SendPulse sends a POST request to the specified URL with the JSON data type.

Data is sent every minute or when the limit of 1000 events is reached.

Data is sent in the following format:

[
  {
    "event": "event_name",
    "timestamp": 1490954061,
    "message_id": 1149317311,
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  }
]

If there are several events, then they will be grouped into one or several requests:

[
  {
    "event": "event_name",
    "timestamp": 1490954061,
    "message_id": 1149317311,
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  },
  {
    "event": "event_name",
    "timestamp": 1490954062,
    "message_id": 1149317311,
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  },
  {
    "event": "event_name",
    "timestamp": 1490954063,
    "message_id": 1149317311,
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "utf8_hello_world" 
  },
]

Request Formats, Depending on the Event

Delivered:

[
  {
    "smtp_server_response_code": "250",
    "smtp_server_response_subcode": "",
    "sender": "john.doe@sendpulse.com",
    "smtp_server_response": "custom_text_response_from_recipients_server",
    "timestamp": 1490953933,
    "message_id": 1149317311,
    "recipient": "doe.john@sendpulse.com",
    "event": "delivered",
    "subject": "utf8_hello_world" 
  }
]

Not delivered:

[
  {
    "smtp_server_response_code": "554",
    "smtp_server_response_subcode": "5.7.1",
    "sender": "john.doe@sendpulse.com",
    "smtp_server_response": "custom_text_response_from_recipients_server",
    "timestamp": 1490956117,
    "message_id": 1149317311,
    "recipient": "doe.john@sendpulse.com",
    "event": "undelivered",
    "subject": "utf8_hello_world" 
  }
]

Open:

[
  {
    "event": "opened",
    "timestamp": 1490962764,
    "message_id": 1149317311,
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

Folowing a link:

[
  {
    "event": "clicked",
    "timestamp": 1490964928,
    "message_id": 1149317311,
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

Unsubscribed:

[
 {
    "event": "unsubscribed",
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  }
]

Reported as spam:

[
  {
    "event": "spam_by_user",
    "timestamp": 1490964607,
    "message_id": 1145317311,
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

An example of a script that accepts a request in PHP:

<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>

Last Updated: 24.09.2021