Idempotent notification requests

The notifications create API supports idempotent operations to avoid sending the same notification twice. This can be useful when a request is interrupted mid request, or there is an error processing the response.

For example consider the case of:

1. A notifications#create call is made
2. OneSignal processes the request and begins sending the notification
3. A network error occurs and no response is ever received by your client.

Without some kind of correlation key, there is no way to verify the last notification did indeed send. If the notification did send and the request is sent again, your users will see duplicate notifications. If it did not send and the request is not retried, your users might miss important notifications. Fortunately, the idempotency_key field exists on notifications for precisely this reason.

idempotency_key is simply an optional parameter to the notifications#create request that can be used to correlate the notification to your system, and more importantly, ensure that duplicate notifications are not sent.

Keys must be unique v3 or v4 UUID format.

In the example case above, the flow might look something like this:

1. A notifications#create call is made with idempotency_key
2. OneSignal processes the request and begins sending the notification
3. A network error occurs and no response is ever received by your client.
4. A notifications#create call is made again with the same idempotency_key as the previous one.
5. OneSignal recognizes the notification has already begun sending, and returns the result of the previous operation.

The above can happen any number of times. As long as the idempotency_key is the same in each request, only 1 notification will be delivered to your users regardless of the number of times the request is sent to our api.

Because the api will not send a notification if the idempotency_key already exists in our database, it's important to use a good source of randomness when generating the uuid passed.

It's important to note this key is only idempotent for 30 days. After 30 days, the notification could be removed from our system and a notification with the same idempotency_key will be sent again.

📘

Name change!

This idempotency_key property used to be called external_id but caused confusion with our Users alias, so we have added this new property name to reduce confusion. Both will work in this case.