Bug Report: SMS Webhook Payload Doesn't Match Docs

[pawel-mackiewicz]

Describe the Bug
The webhook payload structure for sms:received events doesn't match the structure shown in the documentation. The message text field location and payload structure are different, causing parsing issues.

To Reproduce
Steps to reproduce the behavior:

1. Configure a webhook endpoint to receive sms:received events
2. Send an SMS to the monitored device
3. Inspect the received webhook payload
4. Compare the payload structure with the documentation

Expected vs Actual Behavior

• Expected: Message text should be nested at payload.textMessage.text as shown in docs:

  "payload": {
    "textMessage": { "text": "Android is always a sweet treat!"},
    "phoneNumber": "6505551212",
    "receivedAt": "2024-06-22T15:46:11.000+07:00"
  }

• Actual: Message text is at payload.message with additional fields:

  "payload": {
    "message": "Testing",
    "receivedAt": "2025-12-15T13:10:01.000+01:00",
    "messageId": "xxxxxxxx",
    "phoneNumber": "+48XXXXXXXXX",
    "simNumber": 1
  }

Screenshots
N/A - JSON payload difference

Environment

• App Version: 1.51.3 (1248)
• Mode: Local
• Operation: Receiving SMS
• Integration: Webhook API
• Network Type: Local

Smartphone

• Device: Xperia G8341
• OS: Android
• SIM Card Count: 1

Additional Context
The actual payload structure is flattened and includes undocumented fields (messageId, simNumber). Would be great to update the docs to reflect the real structure so developers can parse webhooks correctly. Thanks!

Checklist Before Submission

• I have described the bug in detail.
• I have provided the steps to reproduce.
• I have included screenshots (if applicable).
• I have provided environment details.
• I have included relevant log file excerpts (if applicable).
• I have read [FAQ](https://sms-gate.app/faq/general/) and other relevant information.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• API not invoked when receiving an "RCS Chat" message and no error message in logs #295
• webhook is not working. #276
• Webhook events not triggering on server #281
• Duplicate webhooks sent for a single received SMS #291
• Webhooks errors #286
• Messages that failed show status delivered #181

🔗 Related PRs

#224 - [webhooks] add deviceId field to the API for compatibility with Clo… [merged]
#258 - [receiver] basic MMS support in webhooks [merged]

👤 Suggested Assignees

• capcom6
• chrisco484
• jacksnodgrass
• mesibug
• diaa00

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[capcom6]

Hello!

Thank you for reporting this issue.

You are correct - there was an invalid example in the Getting Started guide. I will update it shortly to match the actual structure.

The up-to-date payload documentation for the sms:received event can be found here: https://docs.sms-gate.app/features/webhooks/

The correct payload structure is:

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:received",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "abc123",
    "message": "Android is always a sweet treat!",
    "phoneNumber": "6505551212",
    "simNumber": 1,
    "receivedAt": "2024-06-22T15:46:11.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

Thank you again for helping keep the documentation accurate. Please let me know if you encounter any other discrepancies.

[github-actions]

This issue is stale because it has been open for 7 days with no activity.

[github-actions]

This issue was closed because it has been inactive for 7 days since being marked as stale.