Sarv.com

PHP

Choose Language

Webhook Calls

Info! This is Beta version, if you have any problem in using API, please mail us at support@sarv.com

/settings/addWebhook

Add a new Webhook

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->settings->addWebhook(url, event, description, store_log);
        print_r($result);
        /*
        Array
        (
            [status] => "success"
            [message] => "Webhook Added"
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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 Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
url* string a valid url ,that always response 'God bless you, Sarv'
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
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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/editWebhook

Edit Webhook

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->settings->editWebhook(webhook_id, url, event, description, store_log);
        print_r($result);
        /*
        Array
        (
            [status] => "success"
            [message] => "Webhook Edited"
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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 Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
webhook_id* string a valid webhook_id
url* string a valid url ,that always response 'God bless you, Sarv'
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
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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/keyResetWebhook

Key Reset for Webhook

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->settings->keyResetWebhook(webhook_id);
        print_r($result);
        /*
        Array
        (
            [status] => "success"
            [message] => "Webhook key reseted"
            [webhook_id] => "424353445757557577457"
            [key] => "2fg345gy6r7"
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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 Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES 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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/listWebhook

List Webhooks

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->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
                                ),
                                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
                                )
                            )
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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 Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES 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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/deleteWebhook

Delete Webhook

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->settings->deleteWebhook(webhook_id);
        print_r($result);
        /*
        Array
        (
            [status] => success
            [message] => "Webhook Deleted"
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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 Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES 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
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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/settings/getWebhookInfo

Get info of any webhook

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $result = $sarv->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(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error 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


Array
(
    [status]=> "error"
    [code]=> -1
    [name]=> "AuthenticationError"
    [message]=> "Token MissMatch"
)
Parameters
owner_id* string a valid Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
webhook_id* string valid webhook id
* compulsory field
Return Value: Success
struct the results of webhook info
status string 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
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. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

Webhook Format

Every SarvTES 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) - sarvtes_events.

The sarvtes_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": 1465988183000,
	"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": 1465988314000,
	"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: b0df23337efdcda913f1e8888014812b@example.com\r\nOriginal-Mail-From: b-60821810-purchase=example.com@example.org\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

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

Verifying Request Signatures

SarvTES includes an additional HTTP header with webhook POST requests, X-SARVTES-SIGNATURE, which will contain the signature for the request. To verify a webhook request, generate a signature using the same key that SarvTES uses and compare that to the value of the X-SARVTES-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 SarvTES (including any query strings, if applicable). SarvTES 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-SARVTES-SIGNATURE HTTP header.

Note: Some HMAC implementations can generate either a binary or hexadecimal signature. SarvTES 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 SarvTES 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. SarvTES 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. SarvTES will queue the batch and retry later, which will give you time to update your application with the new key.