Receiving delivery status webhook requests

To check whether your messages have been delivered or not, you can provide an endpoint to receive delivery status webhook requests from our service.

Alternatively, you can query the delivery status endpoint to check delivery status

To check, make a request to the get-delivery-receipts endpoint, with the batch-uuid of the message(s) you want to check

You may also configure webhook delivery receipts to be fowarded directly to your system as soon as they're available. These are configured in the request for both add-message and add-batch.

add-message webhooks

Configure webhooks when using add-message by using the key callback in either the messages array, or defaults object:

• messages.*.callback
• defaults.callback

---

POST https://api.mplus.cymba.co.uk/message

request body

{
    "messages": [
        {
            "from": {
                "type": "custom",
                "value": "sender-id"
            },
            "to": "441111111111",
            "body": "This is a test message!",
            "callback": "https://my-webhook.com/delivery-receipt"
        }
    ]
}

---

response body

{
    "messages": [
        {
            "to": "441111111111",
            "body": "This is my test webhook message",
            "from": {
                "type": "custom",
                "value": "sender-id"
            },
            "callback": "https://my-webhook.com/delivery-receipt",
            "batchUuid": "0214aa87-ecb8-433d-b0c1-837cbbf3d95b",
            "messageUuid": "1e14bc29-fa64-4a69-a7fe-923264f5d3ac",
            "scheduled": false
        }
    ]
}

---

add-batch webhooks

Configure webhooks when using add-batch by using the key callback

---

POST https://api.mplus.cymba.co.uk/message

request body

{
    "from": "mplus-test",
    "message": "This is my test webhook message",
    "destinations": ["441111111111"],
    "callback": "https://my-webhook.com/delivery-receipt",
}

---

response body

{
  "identifier": "0214aa87-ecb8-433d-b0c1-837cbbf3d95b"
}

The identifier field returned is the batch-uuid

Receiving delivery webhooks

Once we have the delivery status, if a webhook endpoint was specified in the original request, we'll attempt to make a request to that endpoint containing the details of delivery.

For this example, we're implying that the callback parameter specified in the original request was https://my-webhook.com/delivery-receipt

---

POST https://my-webhook.com/delivery-receipt

request body

{
    "destination": "+441111111111",
    "delivered": true,
    "batchuuid": "ea5b64d8-4267-4ffa-937d-2ba0c4f031f3",
    "messageuuid": "6a96a54d-596f-403a-bcd6-6a07fd985f93",
    "receiptInfo": {
        "code": "00",
        "description": "Successful"
    }
}

---

expected response code 2xx

---

Additional notes on webhook delivery receipts:

• Webhook requests are retried upon receiving a non-200 response
• Messaging Plus will retry webhook requests up to 5 times