# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.korewireless.com/developers/get-started/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.