Migrating to KORE Callbacks

While using Super SIM and Programmable Wireless, you can receive callbacks when you:

• Perform async update operations to your SIMs

• Receive SMS Commands

• Receive IP Commands

• Order and install eSIM profiles

This document describes how to smoothly transition from receiving callbacks from Twilio's infrastructure to receiving them from KORE's with minimal disruption to your current operations.

KORE will not perform a hard switch to the KORE Webhook system immediately. Instead, you will be able to control which infrastructure the callbacks are sent from by updating your callback URLs and providing a value for the new URL fragment #cbs (for "callback source"). This will give you a chance to test the flow with specific SIMs before all of your callbacks start coming from KORE. Callback payloads will remain unchanged for now; however, request headers sent will change and you may need to make changes to your application to ensure that you correctly accept them. Learn more about changes to the headers below.

Plan to perform testing and make changes to your applications as needed with the following timeline in mind:

• Until October 15, 2024, we will continue to use Twilio's callback infrastructure by default. The current payloads and headers you've been receiving will remain unchanged. You can begin receiving callbacks from KORE though by editing the callback URL.

• After October 15, 2024, we will change the default callback infrastructure from Twilio to KORE. You can continue to receive the callbacks from Twilio's infrastructure if you need more time to complete changes by editing your callback URL to instruct us to still use Twilio's infrastructure. This will work until November 1, 2024. Learn more here.

• After November 1, 2024, all callbacks will be sent from KORE.

By default, the Twilio system will continue to be used for callbacks during this period unless KORE is explicitly specified until October 15, 2024. This approach ensures that your operations remain uninterrupted while you test and adapt to the new system.

At the end of the transition period, KORE will make the KORE Webhook system the default for all callbacks and no longer use the Twilio system. The transition period is crucial for identifying any necessary adjustments to your parsing and handling logic to accommodate changes such as the new headers, idempotency token format, callback signature and sending IP address.

If you have questions, you can contact KORE support.

Key Changes

Source IP

Callbacks from the KORE Webhook system will come from a different IP address than those from Twilio. KORE uses a pool of IP addresses when sending Webhooks, so there is no specific range of IP addresses that KORE will use.

Idempotency Header

The I-Twilio-Idempotency-Token header will be replaced by Kore-Idempotency-Token. This header contains the idempotency token, which you can use to de-duplicate callbacks that are sent more than once (e.g., due to retries). The idempotency token's length will change and may consist of 34 to 43 characters (previously always 36 characters).

The KORE idempotency token header can't be used to de-duplicate Twilio Callbacks, and vice versa.

Request Signature Header

Twilio's callbacks contain a verification header X-Twilio-Signature which you can use to validate their authenticity. This is a Twilio feature and this exact implementation will not be carried over to KORE. This X-Twilio-Signature header will not be sent from KORE.

Instead, KORE callbacks will include a Kore-Signature header. Following our guide, you can use the header value to verify that you received a legitimate callback from us.

If you are using the X-Twilio-Signature to validate the authenticity of Twilio callbacks, you will need to make changes to your application to receive callbacks from KORE.

Other Minor Header Changes

Some changes are expected for the callback's request headers.

• The User-Agent header's content changes from TwilioProxy/1.1 to KoreProxy/1.1.

• The X-Home-Region and X-Use-Static-Proxy headers are removed.

• A new Date header containing the UTC date and time the callback was sent has been added.

How to Transition to KORE

To use the KORE Webhook system during the transition period, you must append a specific URL fragment to your callback URLs. This fragment instructs our system to send callbacks using the KORE Webhook server.

The URL fragment to append is #cbs=kore, where "cbs" stands for "callback source".

For example, if your usual callback URL is https://example.com/path, you should modify it to https://example.com/path#cbs=kore to opt-in to the new Webhook system. If the cbs fragment is not specified, KORE will default to the Twilio system.

URL fragments are processed solely by the sending client and will not be present in the actual request that your server receives.

Testing Your Transition

In general, you can verify that you are successfully receiving callbacks from KORE by using any Super SIM operation that triggers a callback (e.g., certain SIM status updates, sending IP or SMS commands, downloading an eSIM profile).

In this example, we are showing you how to test it by updating a Super SIM's status. We will first deactivate a SIM and request to receive a callback when it completes which will come from Twilio's infrastructure (assuming it's still the default system when you are reading this). We will then reactivate it and request that the callback be sent by KORE.

The following request shows the deactivation of a SIM that is in status active.

curl -u "$API_KEY:$AUTH_TOKEN" -X POST https://supersim.twilio.com/v1/Sims/HSab3f06be8f5d32caecb91e8a306c6c08 \
-d CallbackUrl=http://your-callback-url.com/path?foo=bar \
-d CallbackMethod=POST \
-d Status=inactive

This command will update your SIM's status to inactive and send a callback to your server using the Twilio system. The request that you will receive should look similar to this:

POST /path?foo=bar

REQUEST CONTENT:
ApiVersion=v1&SimUniqueName=my_super_sim&SimSid=HSab3f06be8f5d32caecb91e8a306c6c08&SimStatus=inactive&AccountSid=AC3ba717b1d236e6c4a835e46130267eb4

HEADERS:
Host: your-callback-url.com
User-Agent: TwilioProxy/1.1
Content-Length: 145
Accept: */*
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
I-Twilio-Idempotency-Token: ba8db584-d0ca-4379-3749-a4e21471a62e
X-Forwarded-For: 18.215.253.114
X-Forwarded-Host: your-callback-url.com
X-Forwarded-Proto: http
X-Home-Region: us1
X-Twilio-Signature: rh4rZXy3AfT1HCr7tZMh3/dY2Ss=
Accept-Encoding: gzip

Now, to switch to having KORE send the callback, simply append #cbs=kore to the callback URL, as shown in the following request. Here, we are activating the SIM again so that it returns to its initial status.

curl -u "$API_KEY:$AUTH_TOKEN" -X POST https://supersim.twilio.com/v1/Sims/HSab3f06be8f5d32caecb91e8a306c6c08 \
-d CallbackUrl=http://your-callback-url.com/path?foo=bar#cbs=kore \
-d CallbackMethod=POST \
-d Status=active

The request that your server receives should look very similar to this:

POST /path?foo=bar

REQUEST CONTENT:
ApiVersion=v1&SimUniqueName=my_super_sim&SimSid=HSab3f06be8f5d32caecb91e8a306c6c08&SimStatus=active&AccountSid=AC3ba717b1d236e6c4a835e46130267eb4

HEADERS:
Host: 0956-2003-cf-5743-1000-651f-7e56-33f7-c3b3.ngrok-free.app
User-Agent: KoreProxy/1.1
Content-Length: 161
Accept: */*
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Cookie: foo=bar
Date: 2024-07-03T14:40:58Z
Kore-Idempotency-Token: RQa48ec9b6ef475034c35566c02b654243
Kore-Signature: 2fdbc0ab1394cc8d37b8dabb74634aa9a951021a9b161f9c7a2186dc490b18b9
X-Forwarded-For: 98.80.223.69
X-Forwarded-Host: your-callback-url.com
X-Forwarded-Proto: http

As you can see, the request path and the content of the two callbacks are identical (except for the Status parameter, but that's expected) while the headers show some differences.