To start using the Cloud Integrator with webhook integration, a HTTPS endpoint should be created. The endpoint could be an IP address or a domain name. Depending on customer network security - it is possible that the webhook source IPs should be whitelisted. The following IPs will forward data to the webhook endpoint(s):

52.29.71.11
18.157.211.95

Configuration via Frontend

Webhook Creation

To create a webhook you should at least define an own integration name and an endpoint URL. Further fields that can be specified are:

Authorization-headers for webhooks.
Event Types (Lifecycle and/or Telemetry data)
If you want your non-translated messages to be received in JSON format if parsable

Configuration of a Webhook in the Frontend

Webhook Configuration via API

Webhook Creation

Headers object in the request body should contain authorization and configuration headers that are expected by the customer's endpoint.

Example:

curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "webhook-name-1",
    "url": "https://www.your-endpoint.com/messages1",
    "headers": {"x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"},
    "eventTypes": [{ "type": "TELEMETRY_DATA" }]
}'

Metadata Injection in Webhook Definitions

Webhook definitions support metadata injection in the url and headers fields using placeholders.
These placeholders will be automatically replaced with data from the device that triggered the event, such as telemetry
data or location events.

The following placeholders can be used in the url and headers fields:

Placeholder	Description	Default Value (if unavailable)
`:iccid:`	ICCID of the device	`none`
`:imsi:`	IMSI1 of the device	`none`
`:ip:`	IP address of the device	`none`

ℹ️	If an event does not contain the required data, the corresponding placeholder will be replaced with `none`.

⚠️	If a webhook definition contains an unsupported placeholder, it will remain unchanged.

Examples

Consider the following webhook configuration:

{
    "name": "webhook-name-1",
    "url": "https://www.your-endpoint.com/events?iccid=:iccid:&ip=:ip:&imsi=:imsi:",
    "headers": {
        "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
        "x-device-imsi": ":imsi:",
        "x-device-iccid": ":iccid:",
        "x-device-ip": ":ip:"
    },
    "eventTypes": [{ "type": "TELEMETRY_DATA" }]
}

Scenario - Full Device Metadata Injection

For an event coming from a device with the following attributes:

ICCID: 1234567890123456789
IMSI: 987654321098765
IP: 192.168.1.1

The webhook request will be transformed as follows:

URL:
https://www.your-endpoint.com/events?iccid=1234567890123456789&ip=192.168.1.1&imsi=987654321098765

Headers:

{
    "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "x-device-imsi": "987654321098765",
    "x-device-iccid": "1234567890123456789",
    "x-device-ip": "192.168.1.1"
}

Scenario - Missing Metadata

For an admin log event that is unrelated to a specific device, no metadata can be injected an the placeholders will be
replaced with none.

The webhook request will be transformed as follows:

URL:
https://www.your-endpoint.com/events?iccid=none&ip=none&imsi=none

Headers:

{
    "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "x-device-imsi": "none",
    "x-device-iccid": "none",
    "x-device-ip": "none"
}

Scenario - Unsupported Placeholders

If a webhook definition contains an unsupported placeholder, it will remain unchanged.

{
    "name": "webhook-name-2",
    "url": "https://api.example.com/data?destination=:unknown:",
    "headers": {
        "x-tracking": ":tracking_id:"
    }
}

Since :unknown: and :tracking_id: are not supported, the resulting webhook request will be:

Final URL: https://api.example.com/data?destination=:unknown:
Headers:
```
{
    "x-tracking": ":tracking_id:"
}
```

Get all Integrations

curl --location --request GET 'https://api.1nce.com/management-api/v1/integrate/clouds'

Response Example:

{
  "page":1,
  "pageAmount":1,
  "items":
  [
    {
      "id":"AP3dIUs3c7_Oo2yJYaXWg",
      "name":"test_integration",
      "state":"INTEGRATION_FAILED",
      "type":"WEBHOOK",
      "createdTime":"2022-11-22T12:16:30.814Z",
      "updatedTime":"2022-11-23T08:07:19.354Z",
      "eventTypes":
      [
        {
          "type":"LIFECYCLE",
          "version":"1.0.0"
        },
        {
          "type":"TELEMETRY_DATA",
          "version":"1.0.0"
        }
      ]
    },
    {
      "id":"Jv2cS-pPcy0NdtQ64ycZJ",
      "lastSuccessfulMessageDelivery":"2022-12-07T12:29:51.927Z",
      "name":"beeceptor-webhook-int",
      "state":"INTEGRATION_ACTIVE",
      "type":"WEBHOOK",
      "createdTime":"2022-09-16T11:01:11.390Z",
      "updatedTime":"2022-12-09T11:23:48.609Z",
      "eventTypes":
      [
        {
          "type":"LIFECYCLE",
          "version":"1.0.0"
        },
        {
          "type":"TELEMETRY_DATA",
          "version":"1.0.0"
        }
      ]
    },
    {
      "id":"MzSca5vvHAfJ4MUUCfCGb",
      "name":"rollout-started-int",
      "state":"ROLLOUT_STARTED",
      "type":"AWS",
      "createdTime":"2022-10-17T13:30:15.309Z",
      "updatedTime":"2022-10-17T13:30:15.309Z",
      "eventTypes":
      [
        {
          "type":"LIFECYCLE",
          "version":"1.0.0"
        }
      ]
    }
  ]
}

Integration Edit

To edit your webhook integration via API, you can use following curl request:

curl --request PATCH \
     --url https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
     "eventTypes": [
          {
               "type": "LIFECYCLE"
          }
     ],
     "url": "www.example.com",
     "jsonPayloadEnabled": false
}
'

Test Integration

To send test message to your webhook integration via API, you can use following curl request:

curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/test'

ℹ️	Any metadata injection placeholder will resolve to `none`

Integration Restart

After 5 unsuccessful message attempts for a webhook it will be set to state INTEGRATION_FAILED.

To restart the webhook:

curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/restart'

ℹ️	Any metadata injection placeholder will resolve to `none`