Callback Settings

Overview

Set up callback addresses to receive data callbacks from EngageLab OTP service for "Message Status" and "Notification Messages" and use the callback data for statistical analysis, strategy re-sending, or triggering system alerts.

• Message Status: After a user sends an OTP message, this status includes sent, delivered, read, verified, etc.
• Notification Messages: Mainly system events, such as low verification rate, insufficient balance, etc.

Configure Callback

In the "Configuration Management" -> "Callback Settings" page, click "Configure Callback" to set up the callback for the EngageLab OTP service.

As shown in the image above, sequentially fill in "Callback Description," "Callback Address," "Username," "Authorization," "Callback Events," etc.

• Check the callback events to push information to your specified address when selected events occur.
• Click on the right side of the message status and message response to view corresponding examples.

Configure Callback Address

When configuring the callback address, the EngageLab OTP

system will send an HTTP POST request to the address. The corresponding developer service must respond with an HTTP status code 200 within 3 seconds, otherwise, the system will consider the address invalid.

• The developer service only needs to respond with an HTTP status code 200, without returning any response message.

Request Example

Suppose the configured callback address is https://example.engagelabotp.callback.com. We will send the following empty message to the address, represented with a curl command:

          curl -X POST https://example.engagelabotp.callback.com -d ''

        

Response Example

The developer service at the callback address should only respond with an HTTP 200 status code after receiving the POST request, as shown below:

          HTTP/1.1 200 OK
Content-Length: 0

        

Callback Address Security Mechanism Configuration

• Username Setting

This is an optional operation. If a username is set, a secret must also be filled in.

To ensure the message's origin is Engagelab, you may choose to authenticate the POST data's source.

After configuring the username and secret, data sent by EngageLab will include the HTTP Header: X-CALLBACK-ID. X-CALLBACK-ID value will be timestamp={timestamp};nonce={nonce};username={username};signature={signature}

For example:

          X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

        

The timestamp is the callback message's timestamp (standard), nonce is a random number, and the signature is the signature information. The signature method is: signature=HMAC-SHA256(secret, timestamp+nonce+username),

Here's a Python code example to calculate signature:

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

        

• Authorization Setting

This is an optional operation. If your callback address requires authentication for requests from EngageLab, please provide the authentication information here. EngageLab will include this Authorization in the request.

Callback Request Body

When a callback event is triggered, the EnageLab OTP system service will send data to the callback address.

"Message Status" Request Example

Message status includes:

• plan: Planned for sending
• sent: Sent
• sent_failed: Sending failed
• delivered: Delivered
• delivered_failed: Delivery failed
• verified: Verified
• verified_failed: Verification failed
• verified_timeout: Verification timed out

          {
    "total": 2,					// Total count
    "rows": [{                  // Data
        "message_id": "1742442805608914944",    // Message ID
        "to": "+8615989574757",            // Receiver
        "server": "otp",                    // Service, fixed as otp
        "channel": "otp",                   // Channel, fixed as otp
        "itime": 1704265712,                // Creation time of this data
        "status": {                         // Message status
            "message_status": "plan",       // Message status, 'plan' for planned sending, 'sent' for sent, 'sent_failed' for sending failed
            "status_data": {                // Status data
                "msg_time": 170426571,     // Message send time
                "message_id": "1742442805608914944",    // Message ID
                "current_send_channel": "",             // Current send channel, values are sms, email, voice, whatsapp, empty when 'plan'
                "template_key": "auto_create_templateu25az170295320745",    // Template key
                "business_id": "100917676394736"        // business ID
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "current_send_channel": "whatsapp",
                "template_key": "auto_create_templateu25az170295320

745",
                "+ business_id": "100917676394736"
            },
            "error_code":5001,      // Error code
            "error_detail":{    // Error details
                "message":"sender config is invalid"        // Error message
            }
        }
    }]
}

        

"Notification Messages" Request Example

Events:

• insufficient_balance: Balance below alert threshold

          {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // Current balance；
                "balance_threshold": 2                       // Alert threshold；
            }
        }
    }]
}