---
title: "Webhook Integrations"
canonical: "https://help.scopious.co.nz/space/KB/248414210/Webhook%20Integrations"
format: markdown
---
[Webhooks](https://scopious.atlassian.net/wiki/spaces/KB/pages/85917701/Glossary+of+Terms#Webhook-Integration) allow sending device data packets to specific HTTP(S) endpoints.

> Macro (toc)

## Who is it for?

Webhooks can be used to build integrations between Scopious and a platform of your choice by sending received data packets using HTTP protocol.

## How does it work?

Webhooks access an HTTP(S) endpoint to POST device data packets. Your platform must expose this endpoint and listen for the data.

For example, whenever an uplink packet is received, Scopious can send the packet to your endpoint, allowing you to process, store, and visualise the data on an external platform.

## Create a Webhook Integration

Creating a Webhook integration requires you to have an HTTP(S) endpoint available. If you don’t have an endpoint available for testing, you can test with a free service like [webhook.site](https://webhook.site/).

To create a Webhook integration, follow the initial steps in [Create an integration](https://scopious.atlassian.net/wiki/spaces/KB/pages/75146635/Create+an+integration#Create-an-Integration), then do the following:

1. Enter the base **Webhook URL** of your endpoint.
2. Click **Advanced settings**.
3. Select the types of messages to be sent to your endpoint.
  - Ensure **Uplinks from device** is selected to receive uplink packets.
  - For each message enabled you have an option to specify a unique endpoint path. This path will be appended to the base Webhook URL entered above. If no path is specified, messages of that type will be sent to the base Webhook URL.
4. Enter **Authorization header** information. If information is entered an `authorization` header will be attached to all webhook requests. The information will need to include the authorisation type (such as `Basic`, `Bearer`, etc) followed by the authorisation value.
5. Enter **Custom headers **if required. Custom headers will be attached to all webhook requests. Enter the header **name** in the first field and the header **value** in the second field.
6. Click **Create**.

![Create webhook integration.gif](media://a8abc7e8-d98c-4e4a-8c2b-57ae69df485b)

## Security Considerations

1. Use **HTTPS** instead of HTTP.

> ⚠️ We strongly recommend using **HTTPS** (instead of HTTP) to safeguard your information while in transit to your endpoint. Data packets are sent unencrypted, so HTTPS is needed to ensure secure transmission by encrypting the data while in transit, preventing interception and inspection by unauthorized parties.

2. Use an **Authorization** header.

> ⚠️ While an **Authorization** header is optional, we strongly recommend using it to enhance security and prevent unauthorised data injection into your platform.

3. Use **DNS Whitelisting**. The DNS to whitelist is `gowifi.au1.cloud.thethings.industries`.

> ℹ️ Data packets are sent directly from a LoRaWAN network server located in AWS, Sydney, Australia. As IP addresses in cloud clusters are not static and may change over time, we recommend whitelisting our DNS address rather than an IP address (if possible).
> ℹ️ 
> ℹ️ If you are unable to whitelist our DNS address, you will need to whitelist the AWS IPv6 address range `2406:da1c::/36`. This address is used by the EC2 service in the `ap-southwest-2` region defined in AWS’s IP ranges documented [here](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html).

## Webhook Path Variables

Webhook path variables allow you to substitute device and device pool specific variables in webhook paths. 

You can use the following variables in webhook paths:

- `appID` - uniquely identifies the Device Pool
- `devEUI` - uniquely identifies the Device

Path variables can be inserted in the **Base Webhook URL** webhook field or the **Path** field for a particular type of message.

For example, if the **Base URL** is `https://app.example.com/scopious/pool{/appID}` and the **Path** is `/uplink/device{/devEUI}` an uplink from the device `0102030405060709` of device pool `59fe7850-ea15-47ad-97af-48f02af13cb6` will be posted at `https://app.example.com/scopious/pool/59fe7850-ea15-47ad-97af-48f02af13cb6/uplink/device/0102030405060709`.

For more documentation about URL path variables refer to [IETF RFC65700](https://tools.ietf.org/html/rfc6570).

## Data Packet Format

Refer to [this guide](https://scopious.atlassian.net/wiki/spaces/KB/pages/263847944) for an example of a JSON data packet you can expect to receive.

## Webhook Retries

### Enable Webhook Retries

> ℹ️ Webhook retries is an optional feature and is disabled by default.

To enable Webhook Retries:

1. Navigate to the **Network > Device Pools** page using the navigation menu on the left side of the screen.
2. Select the Device Pool containing the Webhook Integration.
3. Select the **Integrations** tab.
4. Select the Webhook Integration.
5. Edit the **Webhook Information**.
6. Enable **Webhook Retries**.
7. Click **Save Changes**.

### Webhook Retry Behaviour

When a webhook fails, it will be retried up to 7 times over the course of 75 minutes. A webhook is considered failed if it does not return a **2XX** status or takes longer than 10 seconds to respond.

The retry intervals follow an exponential backoff pattern. The initial request is sent as soon as the uplink arrives. The next attempt is made 4 minutes after the first attempt fails, followed by a retry 8 minutes after the second attempt. The subsequent 4 retries are attempted at 15 minute intervals.

In order to avoid overwhelming the endpoint, a 15% jitter is applied to these intervals. This means the first retry interval will take between 3.4 and 4.6 minutes.

## Webhook Suspension

Webhooks will be automatically suspended when too many webhook requests fail within a short period of time.

While a webhook is suspended, all webhook requests to the same failing endpoint are automatically dropped, unless [webhook retries](#Webhook-Retries) are enabled in which case they will be queued and then retried.

When a webhook is suspended, it initially suspends for a period of 30 seconds and then increases to 300 seconds on further failures after re-activation.

To prevent webhooks being accidently suspended, please follow the [webhook best practices guide](#Recommended-Best-Practices).

## Recommended Best Practices

### Basic Guidance

To ensure reliable webhook delivery, follow these basic rules when processing webhook requests:

- Return a **2XX** response quickly.
  - Your endpoint must return a successful (2XX) response within 10 seconds, otherwise the attempt will be marked as failed.
- Always return a **2XX** response for valid requests.
  - If the webhook request is valid but not needed (e.g. irrelevant or duplicate data), still return a 2XX response and ignore the payload.
  - Returning errors for valid requests may trigger retries and increase traffic.
- Only reject invalid requests.
  - Only return a 4XX or 5XX response if the request is invalid (e.g. bad data, failed authentication).
- Only return a 5XX response when there is a temporary issue.
  - If your system is temporarily unavailable, return a 5XX response so the request can be retried.

### Advanced Technical Guidance

To build robust and scalable webhook integrations, we recommend following these practices:

- Acknowledge first, then process asynchronously.
  - Validate the request, return a 2XX response immediately, and then process the data asynchronously (e.g. via a queue or background worker).
- Separate transport success from business logic.
  - HTTP response codes should reflect whether the request was successfully received and validated, not whether your application used the data.
  - With valid but unwanted events, still return 2XX.
- Log and monitor discarded requests.
  - Even when requests are ignored (e.g. filtered, duplicate, or unwanted), logging them can help with debugging and data reconciliation.
- Handle duplicate events.
  - Webhook deliveries may be retried, so implement idempotency to ensure your system can safely handle duplicate events.
- Handle out-of-order events.
  - Events may not arrive in chronological order due to retries or network delays, so use packet timestamps to determine correct ordering of events.
- **Design for burst traffic and backpressure.**
  - Data packets may be sent in bursts (e.g. after network reconnections, server restarts, etc).
  - Use buffering or queueing to absorb spikes and prevent timeouts.
- Validate and secure your endpoint.
  - Reject requests with a non-2XX error code when:
    - Authentication or signature verification fails
    - Payloads are malformed
    - Required fields are missing
- Use 5XX responses for transient failures only.
  - Only return 5XX when your system cannot temporarily accept requests.
  - Persistent 5XX responses may lead to retries, increased load, and eventual webhook suspension.
- Monitor retries and failures.
  - Repeated non-2XX responses can trigger retries and increase traffic.
  - If no successful responses occur within a retry window, webhook delivery may be temporarily suspended.