How Do I Implement Webhooks for RCS Events?

RCS Webhooks: Implementation Guide

Webhooks let you receive real-time RCS events instead of polling.

Common Webhook Events

Message Status Events:

• message.queued — Message accepted
• message.sent — Sent to carrier
• message.delivered — Delivered to device
• message.read — Recipient opened (if read receipts enabled)
• message.failed — Delivery failed (with error code)

Engagement Events:

• message.clicked — Recipient tapped button/link
• message.replied — Recipient replied
• message.optout — Recipient opted out via STOP
• message.complained — Recipient marked as spam

Template Events:

• template.approved — Template approved by carrier
• template.rejected — Template rejected (with reason)

Webhook Payload Example

{
  "event": "message.delivered",
  "timestamp": "2024-12-20T14:23:45Z",
  "message_id": "msg_abc123",
  "recipient": "+1234567890",
  "channel": "rcs",
  "carrier": "verizon",
  "metadata": {
    "campaign_id": "cart_recovery_dec",
    "user_id": "user_456"
  }
}

Webhook Security

1. Signature Verification

Most providers sign webhooks with HMAC:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

2. HTTPS Only

• Webhooks must use HTTPS (not HTTP)
• Valid SSL certificate required
• TLS 1.2+ recommended

3. IP Whitelisting

• Some providers publish webhook IPs
• Restrict your endpoint to those IPs
• Additional security layer

Webhook Handler Implementation

Basic webhook receiver:

@app.route('/webhooks/rcs', methods=['POST'])
def handle_webhook():
    # Verify signature
    signature = request.headers.get('X-Webhook-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    # Parse event
    event = request.json
    
    # Process event (idempotently!)
    process_event(event)
    
    # Return 200 quickly (within 5 seconds)
    return 'OK', 200

Idempotent Processing

Webhooks can be delivered multiple times. Process events idempotently:

def process_event(event):
    # Check if already processed
    if is_already_processed(event['message_id'], event['event']):
        return  # Skip duplicate
    
    # Process the event
    update_database(event)
    
    # Mark as processed
    mark_as_processed(event['message_id'], event['event'])

Retry Logic

Most providers retry failed webhooks:

• Retry 1: Immediate
• Retry 2: After 1 minute
• Retry 3: After 5 minutes
• Retry 4: After 30 minutes
• Retry 5: After 2 hours

Your webhook should:

• Return 200 quickly (within 5 seconds)
• Process events asynchronously if needed
• Handle retries gracefully (idempotent)

Testing Webhooks Locally

Tools for testing:

• webhook.site — Online webhook receiver
• ngrok — Expose local server publicly
• RequestBin — Inspect webhook payloads

Test scenarios:

• Successful delivery webhook
• Failed delivery with error code
• User click webhook
• User reply webhook
• User opt-out webhook
• Invalid signature (should reject)
• Slow response (should retry)

Monitoring Webhooks

Track:

• Webhook delivery success rate (target: >99%)
• Webhook processing time (target: <2 seconds)
• Failed webhooks and reasons
• Retry attempts and success

Alert on:

• Webhook failure rate >1%
• Processing time >5 seconds
• Endpoint downtime
• Signature verification failures

Common Webhook Issues

Slow processing:

• Don't process synchronously in webhook handler
• Queue events and process async
• Return 200 immediately

Missing events:

• Implement proper retry handling
• Check provider logs for failed deliveries
• Have backup polling for critical events

Duplicate events:

• Use idempotency keys
• Track processed events
• Deduplicate based on event ID + timestamp

Security vulnerabilities:

• Always verify signatures
• Use HTTPS only
• Implement rate limiting on your endpoint
• Keep webhook secrets secure

The Bottom Line

Webhooks are essential for real-time RCS event processing. Implement signature verification, handle retries, process idempotently, and monitor delivery.

Most webhook issues are preventable with proper design. Invest in solid webhook infrastructure upfront.