Enable webhooks for Email service

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 create and send webhooks automatically, go to the Account Settings section in the API tab and click Create a webhook.

Select the event triggered by the webhook in the email service regarding sending an email:

• email marked as spam;
• email opened;
• link in the email clicked;
• new subscriber;
• subscriber unsubscribed;
• subscriber deleted from the list;
• delivered;
• campaign status changed,
• soft bounces,
• hard bounces.

Next, specify the URL, to which notifications will be sent.

For each event, you should create separate webhooks.

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 100 events is reached.

Data is sent in the following format:

[
  {
    "timestamp": "1496827422",
    "event": "event_name",
    "task_id": "3668141",
    "email": "[email protected]" 
  }
]

Request formats, depending on the event

Marked as spam:

[
  {
    "timestamp": "1496827422",
    "event": "spam",
    "task_id": "3668141",
    "email": "[email protected]" 
  }
]

Email opened:

[
  {
    "task_id": "3668141",
    "timestamp": "1496827941",
    "open_device": "Desktop",
    "open_platform": "Windows",
    "browser_ver": "11.0",
    "browser_name": "Firefox",
    "email": "[email protected]",
    "event": "open" 
   }
]

Link clicked:

[
   {
    "link_url": http://google.com,
    "task_id": "3668141",
    "timestamp": "1496828000",
    "open_device": "Desktop",
    "open_platform": "Linux",
    "browser_ver": "58.0.3029.110",
    "browser_name": "Chrome",
    "link_id": "71741389",
    "email": "[email protected]",
    "event": "redirect" 
  }
]

Client opted-out:

[
  {
    "task_id": "3668141",
    "timestamp": "1496827872",
    "from_all": "1",
    "email": "[email protected]",
    "reason": null,
    "book_id": "490686",
    "event": "unsubscribe",
    "categories": "" 
  }
]

New subscriber:

[
  {
    "timestamp":"1496827625",
    "variables": [],
    "email": "[email protected]",
    "source": "address book",
    "book_id": "490686",
    "event": "new_emails" 
  },
  {
    "timestamp": "1496827625",
    "variables": [],
    "email": "[email protected]",
    "source": "subscription form",
    "book_id": "490686",
    "event": "new_emails" 
  }
]

Removing from an email list:

[
  {
    "timestamp": "1496827422",
    "event": "delete",
    "book_id": "490686",
    "email": "[email protected]" 
  }
]

Delivered:

[
  {
    "timestamp": 1632316421
    "event": "delivered"
    "task_id": 9333331
    "email": "[email protected]"
  }
]

Changing email campaign status:

[
  {
    "status": "approve",
    "status_explain": "Approved and will be sent",
    "task_id": "3668138,
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "approve_part",
    "status_explain": "Approved and will be sent by parts",
    "task_id": "3668139",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "only_active",
    "status_explain": "Will be sent only to active adresses",
    "task_id": "3668140",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "confirm_addresses",
    "status_explain": "Rejected: confirm the mailing list",
    "task_id": "3668142",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "need_edit",
    "status_explain": "Rejected: edit the email body",
    "task_id": "3668143",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "rejected",
    "status_explain": "Campaign rejected",
    "task_id": "3668144",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "on_moderation",
    "status_explain": "Campaign is on moderation",
    "task_id": "3668145",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "sending",
    "status_explain": "Campaign is in the sending queue",
    "task_id": "3668146",
    "timestamp": "1496827843",
    "book_id": "490686",
    "event": "task_status_update" 
  },
]

Received soft bounce:

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

Received hard bounce:

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

Example of the script that processes a webhook in PHP:

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

Last Updated: 13.12.2023