Skip to content

07-webhooks.md

Latest commit

 

History

History
95 lines (70 loc) · 3 KB

07-webhooks.md

File metadata and controls

95 lines (70 loc) · 3 KB
Raw

Webhooks

Sendium can call external HTTP endpoints for delivery receipts and mobile-originated messages.

Delivery Receipt Callbacks

HTTP submissions can include a dlr-url query parameter. Sendium stores the callback URL with the submitted message and calls it when the message state changes.

Example HTTP submission:

curl -G http://localhost:8080/sendsms \
  --data-urlencode "username=myuser" \
  --data-urlencode "password=example-password" \
  --data-urlencode "from=Sendium" \
  --data-urlencode "to=306912345678" \
  --data-urlencode "text=Hello from Sendium" \
  --data-urlencode "dlr-url=https://example.com/dlr?msgid=%s&status=%d"

DLR URL Placeholders

Placeholder Value
%d Kannel-style DLR status type.
%s Gateway message ID when available.

DLR Status Values

Value Meaning
1 Delivered.
2 Failed.
4 Buffered or accepted for processing.
8 Submitted to SMSC.

DLR callbacks are sent as HTTP GET requests. HTTP status codes from 200 to 399 are treated as successful. Failed callback attempts are retried up to 10 times with a 120 second delay between attempts.

Mobile-Originated Message Forwarding

Incoming MO messages received from an upstream SMPP connection can be forwarded to an HTTP endpoint using SMPP client worker settings.

outSms.instance.testRoute.forward.mo.url = https://example.com/mo
outSms.instance.testRoute.forward.mo.format = JSON

Forward Formats

Format Behavior
JSON Sends a JSON request body.
FORM Sends an application/x-www-form-urlencoded request body.

MO Fields

Field Description
from Originating address.
to Destination address.
text Message text.
timestamp Message timestamp.
ingateway Inbound gateway identifier.
messageCenter Message center value.
dataCoding SMPP data coding value.

MO URL Placeholders

The forwarding URL may contain placeholders. Values are URL-encoded before replacement.

Placeholder Value
%p Originating address (from).
%P Destination address (to).
%a Message text.
%t Timestamp.
%i Inbound gateway identifier.
%I Message center.
%o Data coding value.

Example with placeholders:

outSms.instance.testRoute.forward.mo.url = https://example.com/mo?from=%p&to=%P&text=%a
outSms.instance.testRoute.forward.mo.format = FORM

MO callbacks are sent as HTTP POST requests. HTTP status codes from 200 to 399 are treated as successful. Failed callback attempts are retried up to 10 times with a 120 second delay between attempts.

Security Notes

  • Use HTTPS webhook URLs in production.
  • Treat callback payloads as untrusted input on the receiving system.
  • Avoid embedding secrets directly in callback URLs when possible.
  • Do not post real callback URLs, credentials, phone numbers, or message bodies in public issues.