SMS Status Event Webhook Configuration
This section explains how users can configure webhooks in the Easify application to receive SMS status events. It also outlines how to securely verify the integrity of these events using the provided Signature Verification Secret.
Adding a Webhook URL
Steps to Add a Webhook:
- Go to Settings -> API Settings -> SMS -> Status Update.
Webhook Event Structure:
When an event is triggered, the application will send a POST request to the configured webhook URL with the following headers and body:
Headers
- X-Easify-Signature: A Base64-encoded signature of the payload, generated using the verification secret.
- X-Easify-Timestamp: The UNIX timestamp of the request.
Payload
The POST body contains the event data. Example:
{
"sms_id": "63f7a88b2e4b6c001f33****",
"sender": "+1234567***",
"receiver": "+0987654***",
"sms_type": "sms",
"message": "Hai.",
"media_url": "",
"status": "Delivered",
"remarks": "",
"created_at": "2025-01-16 10:45:00"
}
Steps for Validating the Signature
Extract Header and Payload Information
X-Easify-Timestamp from the request headers.
X-Easify-Signature from the request headers.
Raw JSON payload from the request body
Extract Header and Payload Information
To validate the signature, recreate it using the following process:
- Use the raw JSON payload as the input:
$payloadString = json_encode($payload);
- Generate an HMAC signature using the shared webhook_secret:
$computedSignature = hash_hmac('sha256', $payloadString, $webhook_secret)
- Encode the generated signature in Base64:
$computedSignatureBase64 = base64_encode($computedSignature);
Compare the Signatures
Compare the computed signature with the one received in the X-Easify-Signature header:
if (hash_equals($computedSignatureBase64, $receivedSignature)) {
// Signature is valid
} else {
// Signature is invalid
}
Validate the Timestamp
To prevent replay attacks, ensure that the timestamp in X-Easify-Timestamp is within an acceptable range (e.g., ±15 minutes):
$currentTime = time();
if (abs ($currentTime - $receivedTimestamp) > 900) {
// 15 minutes
// Reject the request as expired
}
Incoming SMS Webhook Configuration
This section explains how users can configure webhooks in the Easify application to handle incoming SMS messages. It also details how to securely verify the authenticity of each request using the provided Signature Verification Secret.
Adding a Webhook URL
Steps to Add a Webhook:
- Go to Settings -> API Settings -> SMS -> Incoming.
Webhook Structure:
When an incoming SMS is received, the application will send a POST request to the configured webhook URL with the following headers and body:
Headers
- X-Easify-Signature: A Base64-encoded signature of the payload, generated using the verification secret.
- X-Easify-Timestamp: The UNIX timestamp of the request.
Payload
The POST body contains the event data. Example:
{
"sms_id": 172789,
"sender": "+1234567***",
"receiver": "+0987654***",
"sms_type": "sms",
"message": "Hai.",
"media_url": "",
"created_at": "2025-05-14T05:18:41.000000Z"
}
Steps for Validating the Signature
Extract Header and Payload Information
X-Easify-Timestamp from the request headers.
X-Easify-Signature from the request headers.
Raw JSON payload from the request body
Extract Header and Payload Information
To validate the signature, recreate it using the following process:
- Use the raw JSON payload as the input:
$payloadString = json_encode($payload);
- Generate an HMAC signature using the shared webhook_secret:
$computedSignature = hash_hmac('sha256', $payloadString, $webhook_secret)
- Encode the generated signature in Base64:
$computedSignatureBase64 = base64_encode($computedSignature);
Compare the Signatures
Compare the computed signature with the one received in the X-Easify-Signature header:
if (hash_equals($computedSignatureBase64, $receivedSignature)) {
// Signature is valid
} else {
// Signature is invalid
}
Validate the Timestamp
To prevent replay attacks, ensure that the timestamp in X-Easify-Timestamp is within an acceptable range (e.g., ±15 minutes):
$currentTime = time();
if (abs ($currentTime - $receivedTimestamp) > 900) {
// 15 minutes
// Reject the request as expired
}