WebHooks

After you submit an email delivery request to Aurora SendCloud, the system synchronously returns the request result (such as whether the request was accepted). The final delivery result of the email (such as whether it was successfully delivered) and other interaction events (such as opens and clicks) are asynchronously pushed to your specified server via WebHook.

Instead of requiring you to poll for updates, Aurora SendCloud actively pushes data to you in real-time when key events occur. This enables subsequent processes like data synchronization, statistical analysis, and triggering business workflows.

How It Works

Event Occurs: When an email-related event occurs (such as an email being opened, a recipient clicking a link, or the email bouncing), Aurora SendCloud generates corresponding data.

Trigger Notification: Aurora SendCloud immediately sends an HTTP POST request to the URL you configured in your account settings.

Data Transfer: The event data is contained within the body of the POST request, typically encoded in JSON format.

Receive & Process: Your server receives the request, parses the data, and handles subsequent business logic (such as updating a database or sending an internal alert) based on the event type.

Supported Event Types

Currently, Aurora SendCloud supports notifications for the following event types (partial list of common events):

For the complete official list of event types and their detailed payload formats, please refer to the [WebHook Event Format Documentation].

Configuration & Usage Steps

Set the WebHook URL: Log in to the Aurora SendCloud platform, navigate to the WebHook settings page, and specify the API endpoint URL on your server that will receive the events.

Validate the Endpoint: Ensure your server can correctly handle any validation requests sent by Aurora SendCloud to confirm URL accessibility.

Parse Event Data: Write code to parse the JSON data in the POST request body and handle it accordingly based on the event type (such as identified by an event field).

Return Success Status: After successfully receiving and processing the data, your server should return a 2xx HTTP status code (such as 200 OK) to Aurora SendCloud. If a non-2xx status code is returned, Aurora SendCloud may attempt to retry the notification based on its retry policy.

Important Notes

Retry Mechanism: If your server is unreachable or does not return a successful response, Aurora SendCloud will typically retry the notification after a delay, up to a predefined retry limit. The retry schedule is as follows: 1 minute, 10 minutes, 30 minutes, 1 hour, 6 hours, 12 hours, and 24 hours. This provides ample time to resolve any issues before the message is lost. If the retry count is exceeded, Aurora SendCloud will store the message for 15 days. For a repush, please contact us.

Security Verification: It is highly recommended to implement security checks in your endpoint code (such as verifying the request source IP against a whitelist or validating a signature) to ensure requests are genuinely from Aurora SendCloud and prevent spoofing.

Processing Performance: Ensure your receiving endpoint can respond quickly (not longer than 3 seconds) to avoid timeouts that might cause Aurora SendCloud to misinterpret the delivery as a failure.

WebHook Event Description

Requested ( request )

Delivered( deliver )

Open ( open )

Click ( click )

Unsubscribe ( unsubscribe )

Spam Complaint ( report_spam )

Invalid Email ( invalid )

Substat's Return Code and Description

Soft Bounce ( soft_bounce )

Substat's Return Code and Description

Inbound Route (route)

Note:

1. When you do not pass in a custom Message-ID, the Message-ID in reference is automatically generated according to the platform rules, and the prefix of the Message-ID is the same as the prefix of the emailid. When you pass in a custom Message-ID through an SMTP request, the Message-ID in reference will be the Message-ID you passed in. When the reply email does not match the parent email, it will be empty.
2. eg："reference"："[email protected] (opens new window) " #ifaxin.com is the send domain name.
3. Java parsing EML file example,click here download

Code examples

Python example

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Hex;

public boolean verify(String appkey, String token, long timestamp,
            String signature) throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(appkey.getBytes(),"HmacSHA256");
    sha256HMAC.init(secretKey);
    StringBuffer buf = new StringBuffer();
    buf.append(timestamp).append(token);
    String signatureCal = new String(Hex.encodeHex(sha256HMAC.doFinal(buf
            .toString().getBytes())));
    return signatureCal.equals(signature);
}

import hashlib, hmac
def verify(appkey, token, timestamp, signature):
    return signature == hmac.new(
        key=appkey,
        msg='{}{}'.format(timestamp, token),
        digestmod=hashlib.sha256).hexdigest()

function verify($appkey,$token,$timestamp,$signature){
    $hash="sha256";
    $result=hash_hmac($hash,$timestamp.$token,$appkey);
    return strcmp($result,$signature)==0?1:0;
}

Experience Now

If you don’t have url to receive data,try services of requestb.in or request this to experience WebHook.

1. Click Create a RequestBin to generate an url
2. Configure the URL in Aurora SendCloud to receive event data from WebHook
3. After an operation (request, deliver, open), you can see all POST data of the event in requestb.in