Sarv.com

PYTHON

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


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.addWebhook(url="http://abc.com/wh1.php", event="open,click", description="this webhook for only open and click", store_log="Enable")
    print result
    '''
    {
        "status" : "success",
        "message" : "Webhook Added"
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Success Response


{
    "status" : "success",
    "message" : "Webhook Added"
}

Example Error Response


{
    "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


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.editWebhook(webhook_id="424353120757587577493", url="http://abc.com/wh1.php", event=None, description=None, store_log="Disable")
    print result
    '''
    {
        "status" : "success",
        "message" : "Webhook Edited"
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Success Response


{
    "status" : "success",
    "message" : "Webhook Edited"
}

Example Error Response


{
    "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 Request JSON


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.keyResetWebhook(webhook_id="424353120757587577493")
    print result
    '''
    {
        "status" : "success",
        "message" : "Webhook key reseted",
        "webhook_id" : "424353120757587577493",
        "message" : "2fg345gy6r7"
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Response JSON


{
    "status" : "success",
    "message" : "Webhook key reseted",
    "webhook_id" : "424353120757587577493",
    "message" : "2fg345gy6r7"
}

Example Error Response JSON


{
    "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 Request JSON


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.listWebhook()
    print result
    '''
    {
        "status" : "success",
        "webhook_list" :    [
                                {
                                    "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
                                }
                            ]
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Success Response


{
    "status" : "success",
    "webhook_list" :    [
                            {
                                "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
                            }
                        ]
}

Example Error Response


{
    "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


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.deleteWebhook(webhook_id="424353120757587577493")
    print result
    '''
    {
        "status" : "success",
        "message" : "Webhook Deleted"
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Success Response


{
    "status" : "success",
    "message" : "Webhook Deleted"
}

Example Error Response


{
    "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


try:
    import sarv
    sarv_client = sarv.Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN')
    result = sarv_client.settings.getWebhookInfo(webhook_id="424353120757587577493")
    print result
    '''
    {
        "status" : "success",
        "webhook_data" :    {
                                "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
                            }
    }
    '''
except sarv.Error, e:
    # Sarv errors are thrown as exceptions
    print 'A sarv error occurred: %s - %s' % (e.__class__, e)

Example Success Response


{
    "status" : "success",
    "webhook_data" :    {
                            "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
                        }
}

Example Error Response


{
    "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.