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;
• Opened;
• Following a link;
• Reported as spam;
• Unsubscribed
• Soft bounce
• Hard

Send Data Format

Webhook is triggered every 30 seconds or if SendPulse has collected 500 events to send.

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

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" 
  }
]

Received soft bounce:

[
   {
      "smtp_server_response_code": 550,
      "smtp_server_response_subcode": "5.1.0",
      "task_id": 17076325,
      "smtp_server_response": " vch15@i.ua MX: mx23.i.ua RESP: Mailbox over quota. See http://mail.i.ua/err/4/",
      "timestamp": 1658998170,
      "event": "soft_bounces",
      "email": "example@example.com"
   }
]

Received hard bounce:

[
   {
      "smtp_server_response_code": 550,
      "smtp_server_response_subcode": "5.1.1",
      "task_id": 17076325,
      "smtp_server_response": " example@example.com MX: mx.dereck.cn.ua RESP: 5.1.1 <example@example.com>: Recipient address rejected: User unknown in local recipient table",
      "timestamp": 1658998170,
      "event": "hard_bounces",
      "email": "example@example.com"
   }
]

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: 27.07.2023