SMSHook

Overview

SMSHook is Aurora SendCloud's webhook mechanism that provides real-time notifications about SMS events. When you submit SMS requests, you receive an immediate response, but delivery results and other event notifications are sent asynchronously through SMSHook.

How SMSHook Works

Event Flow

Event Occurs: When an SMS-related event happens (delivery, failure, etc.)
Webhook Triggered: SendCloud sends a POST request to your configured URL
Data Processing: Your application receives and processes the event data
Response Required: Your endpoint must return HTTP 200 within 3 seconds

Supported Events

Event	Code	Description	When Triggered
Requested	1	SMS request received and processed	Request successfully submitted
Delivered	20	Message successfully delivered	Recipient receives the SMS
Suppressed	4	Message blocked or suppressed	Message filtered by carrier or system
Failed	5	Delivery attempt failed	Message delivery unsuccessful
Template Verify	8	Template approval status	Template review completed

Setup Instructions

1. Create Your Webhook Endpoint

Create an HTTP service that:

Accepts POST requests
Responds to GET requests (for testing)
Returns HTTP status 200
Processes webhook data within 3 seconds

2. Configure in SendCloud Dashboard

Navigate to 【SMSHook】 in your dashboard
Select the events you want to monitor
Enter your webhook URL
Save your configuration

Note: SendCloud will test your URL to ensure it responds properly before activation.

Implementation Examples

import hashlib
import hmac
import json

def verify_signature(app_key, token, timestamp, signature):
    """Verify webhook signature"""
    message = f"{timestamp}{token}"
    expected_signature = hmac.new(
        key=app_key.encode('utf-8'),
        msg=message.encode('utf-8'),
        digestmod=hashlib.sha256
    ).hexdigest()
    return expected_signature == signature

def handle_webhook(request):
    """Handle incoming webhook"""
    data = json.loads(request.body)
    
    # Verify signature (recommended)
    if verify_signature(APP_KEY, data['token'], data['timestamp'], data['signature']):
        # Process the event
        event_type = data.get('event')
        
        if event_type == 'delivered':
            handle_delivery_success(data)
        elif event_type == 'failed':
            handle_delivery_failure(data)
        # ... handle other events
        
        return {"status": "success"}, 200
    else:
        return {"error": "Invalid signature"}, 401

Reliability & Error Handling

Retry Mechanism

If your endpoint is unreachable or returns an error, SendCloud will retry:

7 retry attempts with increasing intervals
Intervals: 3min → 10min → 30min → 1hr → 6hr → 12hr → 24hr
Backup storage: Messages saved for 15 days after final retry

Response Requirements

Your webhook endpoint must:

Return HTTP 200 status
Respond within 3 seconds
Handle both GET (testing) and POST (events) requests

Event Reference

Triggered when an SMS request is successfully processed.

Parameters

Parameter	Type	Description
`event`	string	Always "Requested"
`eventType`	int	Always 1
`message`	string	Request status message
`userId`	int	Your user ID
`smsUser`	string	SMS user identifier
`smsIds`	array	List of SMS message IDs
`templateId`	int	Template used for the SMS
`phones`	array	Recipient phone numbers
`timestamp`	long	Event timestamp
`token`	string	Random 50-character string
`signature`	string	Verification signature
`customArgs`	object	Your custom parameters

Example Payload

{
  "event": "Requested",
  "eventType": 1,
  "message": "request",
  "userId": 19999,
  "smsUser": "App",
  "smsIds": ["1652150994014_9373_14466_36735_99drnc$13888888888"],
  "templateId": 29999,
  "phones": ["13888888888"],
  "timestamp": 1652150994087,
  "token": "VDymF6ihuJkKZjHiJZkLKGmY6q9qAQ2WGopLh7mBsDeAO6GKV5",
  "signature": "1ff237043487aeb4dc1b21c22b5ead9e4df94a31a3afa0ad53238eb38c2cbeea",
  "customArgs": {}
}

Best Practices

Security

Always verify webhook signatures
Use HTTPS endpoints
Implement rate limiting
Log all webhook events
Validate all input data

Performance

Respond within 3 seconds
Process events asynchronously
Implement proper error handling
Use database transactions
Monitor endpoint health

Reliability

Make endpoints idempotent
Handle duplicate events gracefully
Implement proper logging
Set up monitoring alerts
Test with various event types

Troubleshooting

Check endpoint accessibility
Verify SSL certificate
Monitor response times
Review error logs
Test signature verification

Need Help?

If you exceed the retry limit or need messages re-pushed, please contact our support team with your webhook configuration details.