Skip to main content

SMS Webhooks

SMS webhooks are a mechanism that allows the client to receive, in real time, events related to the delivery status of transactional SMS messages sent via the Arpoone API.

The URLs configured by the client will be invoked by our server (HTTP POST), sending information in JSON format.

Configuration​

The transactional SMS operation allows for the configuration of 3 webhooks, representing 3 SMS delivery states:

  • Delivered;
  • Pending;
  • Not Delivered.

This configuration is made in the smsWebhooks property of the payload, used in the transactional SMS endpoint, where the client can choose which events they want to be notified about (using the enabled property (bool)).

Each endpoint configured by the client during the SMS send will be associated with a different event related to the sent SMS. Example of configuration (inside the transactional SMS payload):

...
"smsWebhooks": {
    "delivered": {
        "url":"https://your-endpoint-here.com/delivered",
        "enabled": true
    },
    "not_delivered": {
        "url":"https://your-endpoint-here.com/notdelivered",
        "enabled": true
    },
    "pending": {
        "url":"https://your-endpoint-here.com/pending",
        "enabled": true
    },
    "customPayload": "{\"abc\": "123"}"
}
...

Invocations​

The structure of the SMS webhooks that Arpoone will send to each of the endpoints indicated by the client is as follows:

[
    {
        "Msisdn": <string>,
        "Status": <string>,
        "MessageId": <uuidv4>,
        "OrganizationId": <uuidv4>,
        "ReportDescription": <string>,
        "ReportDateTime": <datetime>,
        "TotalSegments": <int>,
	"CustomPayload": <string>
    }
    ...
]

In addition to the granular configuration per endpoint, the webhook indicates — in the Status property — the state of the SMS: DELIVERED, NOT_DELIVERED, or PENDING. Therefore, it is possible to use the same endpoint for all 3 states if desired.

Important: The client must ensure that a HTTP 200 (OK) response is returned upon success; otherwise, the webhook will be retried.

Notes​

  • The DELIVERED and NOT_DELIVERED states are the final delivery statuses for the SMS. However, the PENDING state represents a transitional status in the delivery process of the SMS. Therefore, multiple requests with this status may be sent until a final state is reached. Our system does not guarantee the order of delivery, so the client's business logic should be aware of this rule;

  • Special attention should be given to the fact that in the HTTP request made by Arpoone, the body of the request is an array that can contain one or more webhooks with different states, up to a maximum total of 1000 per HTTP request. It is common that for each SMS sent, an HTTP request is triggered with two webhooks — one with the PENDING state and another with the DELIVERED state (final status);

  • We recommend using the tool https://webhook.site for validation/testing of the webhook functionality, using the "Your Unique URL" value provided by the tool as the endpoint in the webhook configuration;

  • To optimize performance, the client should process the webhooks asynchronously to ensure a quick response time to Arpoone's HTTP requests.