This article provides tips on how to prevent your Push API integration from failing and ultimately being disabled.

The principle cause of Push API failure is not returning an HTTP 2xx response even though you have successfully received a Push API call. Paazl's Push API considers anything other than an HTTP 2xx code to be a sign that something has gone wrong. The number of incorrectly "failed" calls will build up in Paazl's back-end until Paazl is forced to disable the Push API.

If your Push API service has been disabled, you will need to manually re-enable the service in your Paazl web app account. Existing events in the Push API queue or new events that are generated while it is disabled will be lost.

The following tips address common integration mistakes that lead to incorrect Push API responses and to subsequent disabling of the Push API.

Tip 1 - Validate bearer token

Make sure your server inspects, verifies and properly responds to the bearer token that Paazl sends along with its Push API requests. The bearer token is sent in the request's header (see Push API reference for more information). If your server doesn't handle the token properly, the resulting HTTP 404 status code will be treated as a failure by the Paazl Push API.

Tip 2 - Keep server token updated

For security reasons, you will want to periodically generate a new bearer token in your Paazl web app account. This is the security token that Paazl will send with its Push API requests. Make sure you don't forget to also update the server-side bearer token that you are expecting. If Paazl sends the new token and your server is still expecting the old token, an exception will be thrown.

Tip 3 - Keep data validation separate

The Push API request contains data such as an order's reference or barcode. Your webshop correctly validates the data but may return validation errors to the Push API in the form of HTTP 4XX or 5XX status codes.

Please be aware that such exceptions have nothing directly to do with the Push API request itself, which succeeded, or else you wouldn't have received any data to validate. Make sure you separate the two concerns. If a Push API request has succeeded, regardless of what what your webshop does with the information after that, make sure you return an HTTP 200 status code.

Tip 4 - Don't create or confirm orders

The Push API request contains a status element that can have the value CREATED. Your webshop's integration may use the Push API to trigger order creation in your webshop or to confirm orders. Don't use the Push API for order creation or confirmation—it wasn't designed for that purpose. For example, Paazl doesn't promise 100% up-time for its Push API.

In addition, you run the risk of unnecessarily propagating HTTP 4XX or 5XX exceptions to the Rest API. Such exceptions have nothing directly to do with a Push API request itself and may lead to your Push API implementation being disabled.

Tip 5 - Prepare for asynchronous messaging

Be prepared to receive multiple Push notifications per minute. Make sure your integration is asynchronous.