# Webhooks

{% hint style="info" %}
This documentation applies to the following products:

* Super SIM
* Programmable Wireless

Ensure you follow the [guide ](https://www.twilio.com/docs/iot/kore-acquisition/link-your-twilio-kore-accounts)to link your Twilio account to KORE before continuing.

For all other products, please review their respective documentation.
{% endhint %}

Follow these steps to start receiving Webhook events from KORE.

## 1. Securing your Webhook - Secret Generation

Securing your Webhook with a secret isn't mandatory, but KORE strongly encourages you to [validate](https://docs.korewireless.com/developers/how-to/webhooks/validate-webhook-signatures) that the Webhook comes from KORE.

{% hint style="warning" %}
The secret should only be known by you and KORE. Treat this as you would your password, and do not share it.
{% endhint %}

To create your first KORE Webhook secret, log in to the Developer Portal, navigate to the [Webhook page](https://build.korewireless.com/webhook), and click Create.

<figure><img src="https://2506474853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ydryXnnBZcpfzlfF36e%2Fuploads%2FTLyNY6FK7PnPFtdQ6znn%2Fimage.png?alt=media&#x26;token=093d7fe3-a570-4bbf-946f-638ba6bf7be3" alt=""><figcaption></figcaption></figure>

Provide a friendly name to your secret and click Create.

<figure><img src="https://2506474853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ydryXnnBZcpfzlfF36e%2Fuploads%2FMYQPZlhNixhw76IDBbr1%2Fimage.png?alt=media&#x26;token=7c2836d1-de93-4a1b-95da-bdbed2609c46" alt=""><figcaption><p>Enter Friendly name</p></figcaption></figure>

View or download the newly created Secret and save it.

<figure><img src="https://2506474853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ydryXnnBZcpfzlfF36e%2Fuploads%2FZIPVW0IPuruNlzZNhQRt%2Fimage.png?alt=media&#x26;token=213ef360-4ff6-4de7-8b00-5514dceef98c" alt=""><figcaption><p>Record the secret</p></figcaption></figure>

{% hint style="warning" %}
A secret is visible or downloadable only at the time of creation. If you forgot to save it, review our [guide](https://docs.korewireless.com/developers/how-to/webhooks/rotate-my-webhook-secret) to rotate your secret to generate a new one.
{% endhint %}

The newly created secret details will be listed.

<figure><img src="https://2506474853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ydryXnnBZcpfzlfF36e%2Fuploads%2FuVzP0yacM9c3AdSdS8uF%2Fimage.png?alt=media&#x26;token=e0eb2d94-92b0-4079-8b8f-5d241e66d0cb" alt=""><figcaption></figcaption></figure>

Once you have generated your first Webhook secret, all Webhook callbacks from KORE will be signed, and you can then [validate](https://docs.korewireless.com/developers/how-to/webhooks/validate-webhook-signatures).

## 2. Configure a Webhook URL with the Super SIM API

{% hint style="info" %}
The assumptions are:

* You have created an API client to make API calls against KORE with a Super SIM scope; if not, review the [getting started guide](https://docs.korewireless.com/developers/get-started/apis).
* You have SIMs in either an Active or Inactive state.
  {% endhint %}

We will configure a Webhook on a Super SIM API endpoint to get started and flip a SIM's status from inactive to active.&#x20;

{% hint style="warning" %}
Activating a SIM will incur a monthly SIM fee and any data charges you generate.
{% endhint %}

With your API token and Super SIM SID, make the following API call to activate your Super SIM ensuring you specify a value for `CallbackUrl`.

{% code title="Request" lineNumbers="true" %}

```javascript
curl -X POST "https://supersim.api.korewireless.com/v1/Sims/{Sid}" \
--data "Status=active" \
--data "CallbackUrl={Your notification URI}" \
--header 'Authorization: Bearer ACCESS_TOKEN'
```

{% endcode %}

{% code title="Response" lineNumbers="true" %}

```json
{
  "sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "unique_name": "My SIM",
  "status": "new",
  "fleet_sid": null,
  "iccid": "89883070000123456789",
  "date_created": "2021-04-01T20:00:00Z",
  "date_updated": "2021-04-01T20:00:00Z",
  "url": "https://supersim.api.korewireless.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

{% endcode %}

{% hint style="info" %}
If the CallbaackUrl parameter has more than one query parameter, the URL must be data-urlencoded.

For example:

If your callback URL is `https://mycallback.com?foo1=bar1&foo2=bar2`

KORE will send the events to  `https://mycallback.com?foo1=bar1.`

You will need to replace `&` with `%26`. So, the callback URL you specify in the API call should be `https://mycallback.com?foo1=bar1%26foo2=bar2`.

KORE does not look at query parameters when [generating a signature](https://docs.korewireless.com/developers/how-to/webhooks/validate-webhook-signatures).
{% endhint %}

## 4. Receiving and Responding to Webhook

Once you submit your API call with a Webhook configured, you will receive a callback from KORE with the HTTP headers mentioned [here ](https://docs.korewireless.com/developers/webhooks#headers)( a sample is shown below).

<pre><code>POST /path?foo=bar

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

HEADERS:
Host: 0956-2003-cf-5743-1000-651f-7e56-33f7-c3b3.ngrok-free.app
<a data-footnote-ref href="#user-content-fn-1">User-Agent</a>: KoreProxy/1.1
Content-Length: 161
Accept: */*
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded; charset=utf-8
<a data-footnote-ref href="#user-content-fn-2">Date</a>: 2024-07-03T14:40:58Z
<a data-footnote-ref href="#user-content-fn-3">Kore-Idempotency-Token</a>: RQa48ec9b6ef475034c35566c02b654243
<a data-footnote-ref href="#user-content-fn-4">Kore-Signature</a>: 2fdbc0ab1394cc8d37b8dabb74634aa9a951021a9b161f9c7a2186dc490b18b9
X-Forwarded-For: 98.80.223.69
X-Forwarded-Host: your-callback-url.com
X-Forwarded-Proto: http
</code></pre>

Upon receiving this, you should respond with a 2xx HTTP response code. Any temporary failures (HTTP response codes 408, 429, or 5xx) will be automatically retried a pre-determined amount of times, which is defined by the [`Retry Count` Connection Setting](https://docs.korewireless.com/developers/webhooks/connection-settings).

## Next Steps

🎉 Congratulations! You have successfully configured and received a Webhook from KORE.&#x20;

You can explore [KORE's various other APIs](https://docs.korewireless.com/en-us/v/api-reference/) to get started with other products.

[^1]: This will be KoreProxy/1.1

[^2]: Event Date

[^3]: A unique value to deduplicate events

[^4]: KORE Signature to validate the message