Webhooks Calls

Email API API Books Getting Started

Webhooks Calls

Info! Do you have any questions on our Email API? Write to us at[email protected]

/settings/addWebhook

Add a new Webhook


Example Call

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->addWebhook(url, event, description, store_log);
print_r($result);
/*
Array
(
[status] => "success"
[message] => "Webhook Added"
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => "success"
[message] => "Webhook Added"
)


Example Error Response

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN
url* string a valid url ,that always response 'God bless you, PowerEmail'
event string a valid events string with comma separated like 'send,open,click,soft_bounce,hard_bounce,spam'
description string description about webhook
store_log string value is Either 'Enable' OR 'Disable'

* compulsory field

Return Value: Success
struct the results of newly created webhook
status string always success
message string human readable message
Return Value: Error
struct the error results when attempt to create webhook
statusstring error
messagestring human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/editWebhook

Edit Webhook


Example Call

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->editWebhook(webhook_id, url, event, description, store_log);
print_r($result);
/*
Array
(
[status] => "success"
[message] => "Webhook Edited"
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => "success"
[message] => "Webhook Edited"
)


Example Error Response

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN
webhook_id* string a valid webhook_id
url* string a valid url ,that always response 'God bless you, PowerEmail'
event string a valid events string with comma separated like 'send,open,click,soft_bounce,hard_bounce,spam'
description string description about webhook
store_log string value is Either 'Enable' OR 'Disable'

* compulsory field

Return Value: Success
struct the results of updated Webhook
status string always success
message string human readable message
Return Value: Error
struct the error results when attempt to update webhook details
statusstring error
messagestring human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/keyResetWebhook

Key Reset for Webhook


Example Request JSON

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->keyResetWebhook(webhook_id);
print_r($result);
/*
Array
(
[status] => "success"
[message] => "Webhook key reseted"
[webhook_id] => "424353445757557577457"
[key] => "2fg345gy6r7"
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => "success"
[message] => "Webhook key reseted"
[webhook_id] => "424353445757557577457"
[key] => "2fg345gy6r7"
)


Example Error Response

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN
webhook_id* string a valid webhook id

* compulsory field

Return Value: Success
struct the results of key reset for Webhook
status string always success
message string human readable message
webhook_id string webhook id
key string new key
Return Value: Error
struct the error results when attempt to key reset for Webhook
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/listWebhook

List Webhooks


Example Call

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->listWebhook();
print_r($result);
/*
Array
(
[status] => "success"
[webhook_list] => array(
array(
[webhook_id] => "424353445757557577457"
[url] => "http://abc.com/wh1.php"
[event] => "open,click"
[key] => "cgvddgrsd"
[store_log] => "Enable"
[description] => "this webhook for only open and click"
[create_date] => 754453534
),
[webhook_id] => "424353120757587577493"
[url] => "http://abc.com/wh1.php"
[event] => "soft_bounce,click"
[key] => "sdfgdggdgd"
[store_log] => "Disable"
[description] => "this webhook for only soft_bounce and click"
[create_date] => 8350953531
)
)
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => "success"
[webhook_list] => array(
array(
[webhook_id] => "424353445757557577457"
[url] => "http://abc.com/wh1.php"
[event] => "open,click"
[key] => "cgvddgrsd",
[store_log] => "Enable",
[description] => "this webhook for only open and click",
[create_date] => 754453534,
),
array(
[webhook_id] => "424353120757587577493"
[url] => "http://abc.com/wh1.php"
[event] => "soft_bounce,click"
[key] => "sdfgdggdgd",
[store_log] => "Disable",
[description] => "this webhook for only soft_bounce and click",
[create_date] => 8350953531,
)

)

)


Example Error Response

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN

* compulsory field

Return Value: Success
struct the results of List Webhook
status string always success
message string human readable message
webhook_list[]struct information of single webhook
webhook_id string webhook id
url string url
event string event string with comma separated like 'open,click'
description string description about webhook
store_log string value of status is Either 'Enable' OR 'Disable'
key integer key
create_date integer create date in seconds
Return Value: Error
struct the error results when attempt to List Webhook
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/deleteWebhook

Delete Webhook


Example Call

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->deleteWebhook(webhook_id);
print_r($result);
/*
Array
(
[status] => "success"
[message] => "Webhook Deleted"
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => "success"
[message] => "Webhook Deleted"
)


Example Error Response

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN
webhook_id* string valid webhook id

* compulsory field

Return Value: Success
struct the results of Delete Webhook
status string always success
message string human readable message
Return Value: Error
struct the error results when attempt to Delete Webhook
statusstring error
messagestring human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/getWebhookInfo

Get info of any webhook


Example Request JSON

<?php
try {
require_once 'PowerEmailMTA_PHP/PowerEmail.php';
$PowerEmail= new PowerEmail('owner_id', 'token', 'PowerEmailTES_APP_DOMAIN');
$result = $PowerEmail->settings->getWebhookInfo(webhook_id);
print_r($result);
/*
Array
(
[status] => "success"
[webhook_data] => Array
(
[webhook_id] => 405602261459333060372
[url] => http://xyz.com/webhook3.php
[event] => open
[description] => this is desctiptyioj......
[store_log] => Enable
[key] => aVLnPysvkKUU95AFrb47Zr
[create_date] => 1459333060
[last_success] => 1459366666
[total_event] => 23
)
)
*/
} catch (PowerEmail_Error $e) {
// PowerEmailerrors are thrown as exceptions
echo 'A PowerEmailerror occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>


Example Success Response

Array
(
[status] => success
[webhook_data] => Array
(
[webhook_id] => 405602261459333060372
[url] => http: //103.255.101.118/webhook3.php
[event] => open
[description] => this is desctiptyioj......
[store_log] => Enable
[key] => aVLnPysvkKUU95AFrb47Zr
[create_date] => 1459333060,
[last_success] => 0,
[total_event] => 0
)
)


Example Error Response JSON

Array
(
[status] => "error",
[code] => "-1",
[name] => "AuthenticationError",
[message] => Token MissMatch,
)


Parameters
owner_id* string a valid PowerEmailUser Id
token* string a valid token
PowerEmailTES_APP_DOMAIN* string a valid PowerEmailTES APP DOMAIN
webhook_id* string valid webhook id

* compulsory field

Return Value: Success
struct the results of webhook info
statusstring always success
webhook_data struct information of webhook
webhook_id string smtp webhook id
url string webhook url
event string events with comma separate
description string description
store_log string value of store_log is Either 'Enable' OR 'Disable'
key string key
create_date integer create date
last_success integer last success time
total_event integer total event sent on webhook url
Return Value: Error
struct the error results when attempt to get webhook info
statusstring error
messagestring human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. PowerEmailDevelopers will be notified.
AuthenticationError Provided owner_id and token was not matched.

Webhook Format

Every PowerEmailTES webhook uses the same general data format, regardless of the event type. The webhook request is a standard POST request with a single parameter (currently) - PowerEmailtes_events.

The PowerEmailtes_events parameter contains a JSON-encoded array of webhook events, up to a maximum of 1000 events. Each element in the array is a single event, such as an open, click, or delivered event.


Example Request

[{
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "6f708632d96fe1cb0cb15eccc2676323b2615d5309a7896cf002c54d1a6ea4785",
"ts": 1465890656000,
"msg":{
"bounceDesc": "Requested action not taken: mailbox unavailable",
"bounceCodeTrad": 550,
"bounceCodeEnh": "5.2.2"
},
"event": "hard_bounce"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "5H708632d96ty7ub0cb15eccc2676323b2615d87879a7896cf002c54d1a6ea4893",
"ts": 1465890656000,
"msg":{
"bounceDesc": "smtp; 552 5.2.2 Over quota",
"bounceCodeTrad": 472,
"bounceCodeEnh": "4.2.2"
},
"event": "soft_bounce"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "5H708632d96ty7ub0cb15eccc2676323b2615d87879a7896cf002c54d1a6ea4893",
"ts": 1465890656000,
"msg":{},
"event": "send"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "5H708632d96ty7ub0cb15eccc2676323b2615d87879a7896cf002c54d1a6ea4893",
"ts": 1465890656000,
"msg":{},
"event": "delivered"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "",
"ts": 1465890656000,
"msg":{
"clicks": [{
"clickTs": 1465988314000,
"clickUrl": "http://example.com/",
"clickIp": "0.0.0.0",
"clickUa": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",
}]
},
"event": "click"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "",
"ts": 1465890656000,
"msg":{
"opens": [{
"openTs": 1465988314000,
"openIp": "0.0.0.0",
"openUa": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
}]
},
"event": "open"
}, {
"_id": "14304056-C18956K3-AX7C-41E4-8A14-7E1G4HJYCBCD.129.1",
"smtp_name": "smtp87654321",
"x_unique_id": "5H708632d96ty7ub0cb15eccc2676323b2615d87879a7896cf002c54d1a6ea4893",
"ts": 1465890656000,
"msg":{
"feedbackReport": "Arrival-Date: Tue, 14 June 2016 07:50:56 +0000\r\nOriginal-Rcpt-To: [email protected]\r\nOriginal-Mail-From: [email protected]\r\nReported-Domain: example.org\r\nSource-Ip: 0.0.0.0\r\nFeedback-Type: abuse\r\nAbuse-Type: complaint\r\nUser-Agent: ReturnPathFBL/2.0\r\n",
},
"event": "spam"
}, {

Webhook Authentication

PowerEmailTES signs webhook requests so you can (optionally) verify that requests are generated by PowerEmailTES and not a third-party pretending to be PowerEmailTES. If your application exposes sensitive data, you may want to be sure the requests are coming from PowerEmailTES. This isn't required, but offers an additional layer of verification.

Verifying Request Signatures

PowerEmailTES includes an additional HTTP header with webhook POST requests, X-PowerEmailTES-SIGNATURE, which will contain the signature for the request. To verify a webhook request, generate a signature using the same key that PowerEmailTES uses and compare that to the value of the X-PowerEmailTES-SIGNATURE header.

Get your webhook authentication key

When you create a webhook, a key is automatically generated. You can view and reset the key from the Webhooks page in your account.

Generate a signature

In your code that receives or processes webhook requests:

1. Create a string with the webhook's URL, exactly as you entered it in PowerEmailTES (including any query strings, if applicable). PowerEmailTES always signs webhook requests with the exact URL you provided when you configured the webhook. A difference as small as including or removing a trailing slash will prevent the signature from validating.

2. Sort the request's POST variables alphabetically by key.

3. Append each POST variable's key and value to the URL string, with no delimiter.

4. Hash the resulting string with HMAC-SHA1, using your webhook's authentication key to generate a binary signature.

5. Base64 encode the binary signature

6. Compare the binary signature that you generated to the signature provided in the X-PowerEmailTES-SIGNATURE HTTP header.


Note: Some HMAC implementations can generate either a binary or hexadecimal signature. PowerEmailTES generates a binary signature and then Base64-encodes it; using a hexadecimal signature will not work.

Example PHP implementation

/**
* Generates a base64-encoded signature for a PowerEmailTES webhook request.
* @param string $webhook_key the webhook's authentication key
* @param string $url the webhook url
* @param array $params the request's POST parameters
*/
function generateSignature ($webhook_key, $url, $params) {
$signed_data = $url;
ksort($params);
foreach ($params as $key => $value) {
$signed_data .= $key;
$signed_data .= $value;
}

return base64_encode(hash_hmac ('sha1', $signed_data, $webhook_key, true));
}

Considerations

You can reset a webhook's authentication key at any time. PowerEmailTES will immediately begin using the new key to sign requests. To ensure that you don't lose any webhook batches between the time you reset your key and when you update your application to start using that new key, your webhook processor should reject batches with failed signatures with a non-200 status code. PowerEmailTES will queue the batch and retry later, which will give you time to update your application with the new key.




Copyright © 2011 - Covalent Softwares Pvt. Ltd. All Rights Reserved.