Webhooks

📘

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

/settings/addWebhook

Adds a new webhook.

Example Request

{
    "owner_id": "example id",
    "token": "example token",
    "url": "https://example.com/webhook",
    "event": "send",
    "description": "My webhook",
    "store_log": "yes"
}

Example Success Response

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

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of adding a webhook

Return Value: Error

struct — the error results when attempting to add a webhook

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

/settings/editWebhook

Edits an existing webhook.

Example Request

{
    "owner_id": "example id",
    "token": "example token",
    "webhook_id": "webhook123",
    "url": "https://example.com/webhook-updated"
}

Example Success Response

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

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of editing a webhook

Return Value: Error

struct — the error results when attempting to edit a webhook

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

/settings/keyResetWebhook

Resets the authentication key for a webhook.

Example Request

{
    "owner_id": "example id",
    "token": "example token",
    "webhook_id": "webhook123"
}

Example Success Response

{
    "status": "success",
    "webhook_id": "webhook123",
    "key": "newwebhookkey"
}

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of resetting a webhook key

Return Value: Error

struct — the error results when attempting to reset a webhook key

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

/settings/listWebhook

Lists all webhooks for a user.

Example Request

{
    "owner_id": "example id",
    "token": "example token"
}

Example Success Response

{
    "status": "success",
    "webhook_data": [
        {
            "webhook_id": "webhook123",
            "url": "https://example.com/webhook",
            "event": "send",
            "key": "webhookkey",
            "store_log": "yes",
            "description": "My webhook",
            "create_date": 1458034022169
        }
    ]
}

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of listing webhooks

**webhook_data[]**fields:

Return Value: Error

struct — the error results when attempting to list webhooks

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

/settings/deleteWebhook

Deletes a specified webhook.

Example Request

{
    "owner_id": "example id",
    "token": "example token",
    "webhook_id": "webhook123"
}

Example Success Response

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

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of deleting a webhook

Return Value: Error

struct — the error results when attempting to delete a webhook

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

/settings/getWebhookInfo

Retrieves detailed information about a specific webhook.

Example Request

{
    "owner_id": "example id",
    "token": "example token",
    "webhook_id": "webhook123"
}

Example Success Response

{
    "status": "success",
    "webhook_data": {
        "webhook_id": "webhook123",
        "url": "https://example.com/webhook",
        "event": "send",
        "description": "My webhook",
        "store_log": "yes",
        "key": "webhookkey",
        "create_date": 1458034022169,
        "last_success": 1458039067963,
        "total_event": 42
    }
}

Example Error Response

{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}

Parameters

*compulsory field

Return Value: Success

struct — the results of getting webhook info

webhook_datafields:

Return Value: Error

struct — the error results when attempting to get webhook info

Error Types

ValidationError — The parameters passed to the API call are invalid or not provided when required.

GeneralError — An unexpected error occurred processing the request. SendClean Developers will be notified.

AuthenticationError — Provided owner_id and token was not matched.

Webhook Format

Webhooks use POST requests with a SendCleantes_events parameter containing a JSON-encoded array (max 1000 events per request).

Event types include:

• hard_bounce
• soft_bounce
• send
• delivered
• click
• open
• spam

Webhook Authentication

SendClean signs each webhook request using the X-SendCleanTES-SIGNATURE HTTP header. To verify the authenticity of incoming webhook requests:

1. Create a string starting with the webhook URL.
2. Sort all POST variables alphabetically by key.
3. Append each key and its value to the string.
4. Hash the resulting string using HMAC-SHA1 with the webhook key (binary mode).
5. Base64 encode the hash.
6. Compare the result to the value in the X-SendCleanTES-SIGNATURE header.

If the signatures match, the request is authentic.

Example PHP Verification

function verify_webhook($data, $private_key, $signature) {
    $signed_data = $data['url'];
    ksort($data);
    foreach ($data as $key => $value) {
        if ($key != 'signature') {
            $signed_data .= $key . $value;
        }
    }
    $expected_signature = base64_encode(hash_hmac('sha1', $signed_data, $private_key, true));
    return $expected_signature === $signature;
}

📘

Keys can be reset at any time. Webhooks that return a non-200 HTTP status code will be retried.