Best Practices

This page describes various best practices to consider when working with the SMSPortal webhook engine.

Security

To improve your security, you may decide to limit the traffic allowed to your servers from our Domains and IP Addresses. Our webhook notifications will always originate from the following IP addresses:

NOTE 1: SMSPortal's webhook engine is highly redundant and load-balanced so please ensure that your endpoint(s) are reachable from all of the above IP addresses.

---

Always Return an HTTP 2xx Code

To acknowledge receipt of a webhook request, your web server/application must return a 2xx HTTP status code to SMSPortal. All response codes outside this range, including 3xx codes, indicate to SMSPortal that the customer did not receive the request data.

If SMSPortal does not receive a 2xx HTTP status code, the webhook request is requeued to be retried.

After 5 failures to make a webhook request, SMSPortal marks the request as failed and stops trying to send it to your endpoint.

---

Retry Schedule

The SMSPortal webhook engine waits 10 seconds for a response to any HTTP request. This means that after making the HTTP request, if a response isn't received within 10 seconds, the request is considered to have failed. The webhook request will then be requeued to be retried.

Requeued requests are retried up to a maximum of 5 attempts.

SMSPortal uses an exponential back-off retry policy for all webhook notifications.

Even though 10 seconds is the absolute maximum to handle an HTTP request, customers are encouraged to handle requests in as short a time as possible. Customers that are taking long to handle requests will suffer from the Delayed Delivery Policy discussed in another section.

---

Duplicate Webhook Request Handling

To prevent handling duplicates, the customer is encouraged to store the unique identifier associated with the send event (i.e. Id/SentId per send or EventId for multiple sends).

The logic to follow would be to only insert a new record into your data store if the unique identifier is not present in your data store otherwise simply update your records if it is present.

This will enable the handling of multiple submissions (i.e. retries) with the same event data.

---

Delayed Delivery Policy

If a customer's web server/application experiences delivery failures or extensive delays in handling requests, SMSPortal will begin to delay webhook requests going out to that endpoint for a period of time.

This policy forms part of a fair usage policy where "bad actors" can delay outgoing webhook requests to all customers. The functional purpose of delayed delivery is to protect the SMSPortal webhook engine against unhealthy endpoints.

For example, if 7 consecutive HTTP requests to a customer's web server/application fail, SMSPortal will assume that the endpoint is experiencing issues and will delay all subsequent retries and new deliveries for some time, in some cases, up to several hours.

---

Response Optimisation

For optimal performance, your web server/application should behave in the following way:

1. Receive the HTTP request data being posted by the SMSPortal webhook engine.
2. Immediately enqueue that data in your own internal queue (eg. AWS SQS Service, etc.)
3. Respond with a 200 OK, or other 2xx HTTP code.
4. Asynchronously process the webhook requests in your internal queues.

This means the data you receive from the webhook engine should be stored immediately (cached/queued) and processed separately.

Any complex processing on the customer side, involving databases or other logic, could cause a timeout on the webhook engine and you may not receive the posted data again.

---

Future-proofing

SMSPortal will never remove or edit existing parameters or error codes to ensure backward compatibility. We may however add more variables at any time.

Therefore, in developing and maintaining your code, you should not assume that only the current parameters or error codes exist.

---