LogoLogo
ProductsDevelopersAPI ReferenceContact Us
Twilio IoT Acquisition
Twilio IoT Acquisition
  • Twilio IoT is now part of KORE
    • Link Your Twilio & KORE Accounts
    • Self-Service Limitations
    • IoT Customer Support Migration to KORE
    • Frequently Asked Questions (FAQ)
  • Twilio to KORE Migration Guides
    • Migrating to KORE Console
    • Migrating to KORE's APIs
    • Migrating to KORE Callbacks
    • Migrating to KORE Super SIM Connection Events
    • Migrating to KORE's Status Page
    • Migrating to SIM Ordering at KORE
    • Migrating to the New Super SIM Hardware
  • Advisories
    • Upcoming Changes to Developer Experience for Super SIM & Programmable Wireless – April 2024
    • New UI and APIs Available at KORE & More for Super SIM & Programmable Wireless - August 2024
    • KORE Callbacks Available - September 2024
    • KORE Event Streams Available - September 2024
    • KORE Child Accounts Created and Linked to Your Twilio Subaccounts - October 2024
    • Update on Our Migration to KORE - November 2024
    • More on Super SIM and Programmable Wireless Migration to KORE - December 2024
    • KORE Shop, API migration, Programmable Wireless Console - January 2025
    • More on Super SIM migration to KORE - March 2025
    • New Super SIM hardware and applets updates - April 2025
On this page
  • Key Changes
  • Source IP
  • Idempotency Header
  • Request Signature Header
  • Other Minor Header Changes
  • How to Transition to KORE
  • Testing Your Transition

Was this helpful?

  1. Twilio to KORE Migration Guides

Migrating to KORE Callbacks

PreviousMigrating to KORE's APIsNextMigrating to KORE Super SIM Connection Events

Last updated 8 months ago

Was this helpful?

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 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 .

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 .

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

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.

Twilio's callbacks contain a verification header X-Twilio-Signature which you can use to . 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 , you can use the header value to verify that you received a legitimate callback from us.

validate their authenticity
control which infrastructure the callbacks are sent from
below
guide
KORE support