Skip to main content

​
HTTP Web Push DLR

The Ruach SMS API supports HTTP web push delivery reports (DLR) to provide real-time status updates for your SMS messages.

​
Overview

When HTTP Web push DLR is enabled, you can configure a webhook URL to receive delivery status updates in real-time. The system will send HTTP requests to your specified endpoint with delivery information.
If your webhook URL is not available during the transaction, the DLR will be discarded. The default timeout for webhook requests is 10 seconds.

​
Webhook Configuration

To enable webhook delivery reports:
  1. Contact support to enable DLR for your account
  2. Provide your webhook URL to receive delivery reports
  3. Ensure your endpoint responds with 200 OK within 10 seconds

​
Webhook Request Format

Each delivery report is sent as a GET request to your webhook URL with the following parameters: 
http://yourdomain.com/webhook?doneDate={doneDate}&submitDate={submitDate}&errorCode={errorCode}&shortMessage={shortMessage}&status={status}&messageId={messageId}&mobile={mobile}

​
Parameters

​
messageId
string
required
Unique message ID of the SMS
​
mobile
string
required
Mobile number that received the message
​
submitDate
string
required
Date and time when the message was submitted
​
doneDate
string
required
Date and time when the message was processed
​
status
string
required
Current delivery status of the message
​
errorCode
string
required
Error code (if any)
​
shortMessage
string
required
The original message text

​
Delivery Status Values

StatusDescription
DELIVRDMessage successfully delivered
UNDELIVMessage undelivered
EXPIREDMessage expired
DELETEDMessage deleted
UNKNOWNStatus unknown
ACCEPTDMessage accepted by carrier
REJECTDMessage rejected
BLACKLISTNumber is blacklisted

​
Example Webhook Implementation

const express = require('express');
const app = express();

app.get('/webhook', (req, res) => {
  const {
    messageId,
    mobile,
    submitDate,
    doneDate,
    status,
    errorCode,
    shortMessage
  } = req.query;

  // Process the delivery report
  console.log('Delivery Report:', {
    messageId,
    mobile,
    submitDate,
    doneDate,
    status,
    errorCode,
    shortMessage
  });

  // Update your database or trigger actions based on status
  if (status === 'DELIVRD') {
    console.log(`Message ${messageId} delivered to ${mobile}`);
  } else if (status === 'UNDELIV') {
    console.log(`Message ${messageId} failed to deliver to ${mobile}`);
  }

  // Always respond with 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

​
Best Practices

​
1. Fast Response Time

  • Ensure your webhook endpoint responds within 10 seconds
  • Use asynchronous processing for heavy operations
  • Return 200 OK immediately after receiving the request

​
2. Idempotency

  • Handle duplicate webhook calls gracefully
  • Use messageId as a unique identifier
  • Implement proper deduplication logic

​
3. Error Handling

  • Log all webhook requests for debugging
  • Implement retry logic for failed processing
  • Monitor webhook endpoint health

​
4. Security

  • Validate webhook requests
  • Use HTTPS for your webhook endpoint
  • Implement authentication if needed

​
Testing Webhooks

You can test your webhook endpoint using curl: 
curl -X GET "http://yourdomain.com/webhook?messageId=test123&mobile=1234567890&submitDate=2024-01-01%2010:00:00&doneDate=2024-01-01%2010:00:05&status=DELIVRD&errorCode=0&shortMessage=Test%20message"

​
Use Cases

  • Real-time tracking: Monitor message delivery status in real-time
  • Analytics: Track delivery rates and performance metrics
  • Customer service: Provide delivery confirmations to customers
  • Retry logic: Automatically retry failed messages
  • Compliance: Maintain delivery logs for regulatory requirements