Incoming Message Webhook

Webhooks

SMS

When a switch has been configured to use an HTTP webhook, incoming SMS messages will be delivered to it. Webhooks only include authentication details if the switch has been configured to use it. DLR webhook requests are also sent to the specified incoming message URL.

The endpoint should respond with a 200-level HTTP success status code.

SMS Webhook Schema

Name	Type	Description
body	String	The content of the SMS message.
from	String	The originating number for the SMS.
id	String(format:ulid)	The assigned ID for the SMS request.
timestamp	String(format:date-time)	ISO 8601 timestamp indicating when the SMS was first received by the SMS system.
to	String	The destination number for the SMS.
type	Enum:String	The type of webhook event. Always sms for this schema.

SMS Webhook Example

Swift’s request:

POST https://example.com/sms_webhook
Content-Type: application/json
Content-Length: 177

{
  "body": "Hello, World",
  "from": "12003004000",
  "id": "01JDQ0MDBE0YMVD9E96EGRCCV4",
  "timestamp": "2024-06-14T00:00:00.000000Z",
  "to": "12003004001",
  "type": "sms"
}

User’s endpoint response:

HTTP/1.1 204

MMS

When a switch has been configured to use an HTTP webhook, incoming MMS messages will be delivered to it. Webhooks only include Authorization details if the switch has been configured to use it.

The endpoint should respond with a 200-level HTTP success status code.

MMS Webhook Schema

Name	Type	Description
data	MMS Part	Contains part of the content of the MMS message.
from	String	The originating number for the MMS.
id	String	The unique identifier for the MMS message.
timestamp	String(format:date-time)	ISO 8601 timestamp indicating when the MMS was created.
to	String	The destination number for the MMS.
type	Enum:String	The type of webhook event. Always mms for this schema.

MMS Webhook Example

Swift’s request for a multipart MMS:

POST /mms_webhook HTTP/1.1
Content-Type: application/json
Content-Length: 1234

{
    "data": {
        "encoding": "identity",
        "body": "",
        "parts": [
            {
                "encoding": "base64",
                "body": "data",
                "parts": [],
                "headers": {
                    "content-id": "id",
                    "content-location": "id.xml",
                    "content-transfer-encoding": "base64",
                    "content-type": "application/smil; Name=\"id.xml\"; name=\"id.xml\""
                },
                "is_multipart": false
            },
            {
                "encoding": "base64",
                "body": "data",
                "parts": [],
                "headers": {
                    "content-id": "id",
                    "content-location": "id.jpg",
                    "content-transfer-encoding": "base64",
                    "content-type": "image/jpeg; Name=\"id.jpg\"; name=\"id.jpg\""
                },
                "is_multipart": false
            },
            {
                "encoding": "base64",
                "body": "data",
                "parts": [],
                "headers": {
                    "content-id": "id",
                    "content-location": "id.txt",
                    "content-type": "text/plain; Charset=\"UTF-8\"; Name=\"id.txt\"; name=\"id.txt\""
                },
                "is_multipart": false
            }
        ],
        "headers": {
          "*": "string"
        },
        "is_multipart": true
    },
    "id": "01JDP0GJEGZZC1ZNCA3YJ662HN",
    "timestamp": "2024-06-14T00:00:00.000000Z",
    "type": "mms",
    "from": "string",
    "to": "string"

}

Swift’s request for a root only MMS:

POST /mms_webhook HTTP/1.1
Content-Type: application/json
Content-Length: 234

{
  "data": {
    "body": "Hello, World",
    "encoding": "identity",
    "parts": [
      {}
    ],
    "headers": {
      "*": "string"
    },
    "is_multipart": false
  },
  "id": "01JDP0GJEGZZC1ZNCA3YJ662HN",
  "timestamp": "2024-06-14T00:00:00.000000Z",
  "type": "mms",
  "from": "string",
  "to": "string"
}

User’s endpoint response:

HTTP/1.1 204