How to forward SMS to a webhook API endpoint?

Quick Answer: Forward SMS can send your text messages to any HTTP endpoint as a JSON webhook. Create a Webhook destination in the app, enter your endpoint URL, and set up a Shortcuts automation. Your endpoint will receive a POST request with the message content, sender, and timestamp.

What is Webhook SMS Forwarding?

Webhook SMS forwarding automatically sends your text messages to any HTTP endpoint you control. Unlike platform-specific integrations (Slack, Discord, Teams), webhooks give you complete control over how messages are processed. This is ideal for developers building custom integrations, logging systems, or automation workflows.

When a message arrives, Forward SMS sends a POST request to your endpoint with a structured JSON payload containing the message content, sender information, and metadata.

Why Use Webhooks

Webhooks offer flexibility that pre-built integrations can't match:

Custom automation: Trigger any workflow when you receive an SMS - update databases, send notifications, run scripts, or integrate with any service
Data logging: Store all incoming messages in your own database for compliance, analytics, or backup purposes
Multi-service routing: Process messages with your own logic to route them to different destinations based on content or sender
Internal tools: Build SMS-powered features into your internal dashboards and tools
IoT integration: Connect SMS alerts to your IoT systems, home automation, or monitoring infrastructure

Webhook Payload Format

When a message is forwarded, your endpoint receives a POST request with the following JSON payload:

{
  "timestamp": "2025-01-31T14:30:00Z",
  "content": "Your verification code is 123456",
  "sender": "+1234567890",
  "contact": "Bank of Example"
}

Payload Fields

| Field | Type | Description | |-------|------|-------------| | timestamp | string | ISO 8601 formatted timestamp when the message was forwarded | | content | string | The text message content | | sender | string | Phone number of the sender (if available) | | contact | string | Contact name from your address book (if matched) |

Setting Up Webhook Forwarding

Step 1: Download Forward SMS

Download Forward SMS from the App Store.

Step 2: Create a Webhook Destination

Open the app, tap "Add Destination", and select "Webhook". Enter your endpoint URL. The URL must be HTTPS for security.

Step 3: Test Your Endpoint

Use the "Send test message" button to verify your endpoint receives the webhook correctly. Check your server logs to confirm the payload arrived.

Step 4: Set Up Shortcuts Automation

Follow our Shortcuts setup guide to create the automation that triggers message forwarding.

Implementation Examples

Here are examples for handling the webhook in various languages:

Node.js (Express)

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

app.use(express.json());

app.post('/webhook/sms', (req, res) => {
  const { timestamp, content, sender, contact } = req.body;

  console.log(`Received SMS from ${sender}: ${content}`);

  // Process the message (save to database, trigger automation, etc.)

  res.status(200).json({ received: true });
});

app.listen(3000);

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/sms', methods=['POST'])
def handle_sms():
    data = request.json

    sender = data['sender']
    content = data['content']

    print(f"Received SMS from {sender}: {content}")

    # Process the message

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

PHP

<?php
$payload = json_decode(file_get_contents('php://input'), true);

$sender = $payload['sender'];
$content = $payload['content'];
$timestamp = $payload['timestamp'];

error_log("Received SMS from $sender: $content");

// Process the message

http_response_code(200);
echo json_encode(['received' => true]);
?>

Ruby (Sinatra)

require 'sinatra'
require 'json'

post '/webhook/sms' do
  payload = JSON.parse(request.body.read)

  sender = payload['sender']
  content = payload['content']

  puts "Received SMS from #{sender}: #{content}"

  # Process the message

  content_type :json
  { received: true }.to_json
end

Security Considerations

Use HTTPS

Always use HTTPS endpoints to encrypt the webhook payload in transit. Forward SMS requires HTTPS for webhook URLs.

Handle Errors Gracefully

Your endpoint should return a 2xx status code to acknowledge receipt. If Forward SMS receives an error response, it will log the failure.

Troubleshooting

Webhook Not Receiving Messages

Check the URL: Ensure your endpoint URL is correct and accessible from the internet
Verify HTTPS: The URL must use HTTPS, not HTTP
Check firewall rules: Your server must accept incoming POST requests
Test the endpoint: Use the test button in the app to verify connectivity

Messages Arriving Slowly

Check Shortcuts automation: Ensure the automation runs without requiring confirmation
Background App Refresh: Enable this for Forward SMS in iOS Settings
Network issues: Both your iPhone and server need stable internet connections

Payload Not Parsing

Content-Type: The request uses Content-Type: application/json
JSON parsing: Ensure your server correctly parses the JSON body
Character encoding: Messages are UTF-8 encoded

FAQ

Can I forward to multiple webhook endpoints?

Yes, create multiple Webhook destinations in Forward SMS. Each destination can have a different endpoint URL, and all will receive the forwarded messages.

What happens if my endpoint is down?

If your endpoint returns an error or is unreachable, the message forwarding will fail. The app logs these failures for debugging. Consider implementing a fallback or monitoring system.

Is there a rate limit on webhooks?

There's no artificial rate limit from Forward SMS. Messages are forwarded as quickly as they arrive and your endpoint can process them.

Can I filter which messages are forwarded?

Currently, all messages that trigger the Shortcuts automation are forwarded. You can implement filtering logic in your webhook endpoint to ignore unwanted messages.

Can I use HTTP instead of HTTPS?

No, for security reasons Forward SMS requires HTTPS endpoints. This ensures your message data is encrypted in transit.