Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      Integrations

      • Overview
      • Adding Applications
      • Data Formats
      • Payload Formatters
      • Webhooks
        • Creating Webhooks
        • Scheduling Downlinks
        • Webhook Path Variables
        • Webhook Retries
        • Webhook Templates
          • Format
          • Instantiation
          • Adding Webhook Templates
        • Troubleshooting Webhooks
      • Storage Integration
      • Integrate with popular IoT platforms
      • Other integrations
      • Application Packages
      • Examples

      Format

      Updated 11 September 2024 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      Webhook templates are described using the YAML language. Their format is very closely related to that of a normal webhook integration, but with additional fields added.

      Service Description

      All of the webhook templates must contain the following fields which describe the service provided by the template to the user.

      • template-id: The unique identifier of the template.
      • name: The (human readable) name of the service.
      • description: The description of the service.
      • logo-url: The URL of the logo of the service.
      • info-url: The URL of the main page of the service.
      • documentation-url: The URL of the documentation of the service.
      • tts-documentation-url: The URL of the documentation of the service on thethingsindustries.com/docs.

      Here are the differences between info-url, documentation-url and tts-documentation-url:

      • info-url should lead to the home page of the service (i.e. https://www.thethingsnetwork.org/).
      • documentation-url should be used for the location of the documentation on the service’s page (i.e. https://www.thethingsnetwork.org/docs/applications/example/).
      • tts-documentation-url meanwhile should be used for the guides in our documentation (see cloud-integrations).

      Template Fields

      Templates can contain fields which will be filled by the user on instantiation. The fields are provided as a list named fields in the body of the webhook template and contain the following fields:

      • id: The unique identifier of the field. The ID is only referenced internally and not shown to the user.
      • name: The (human readable) name of the field.
      • description: The description of the field.
      • secret: Controls if the contents of the field should be hidden. To be used in the case of secrets such as passwords, tokens or API keys.
      • default-value: The value which should be pre filled for the user initially.

      For more information on the instantiation process, see Instantiation.

      Endpoint

      The endpoint of the webhook can be configured using the following fields:

      • format: The format which the endpoint expects. Currently json and protobuf are supported.
      • headers: A mapping between the names of the headers and their values. The values can contain template fields.
      • create-downlink-api-key: Controls if an API Key specific to the service should be created on instantiation.
      • base-url: The base URL of the endpoint.

      The message paths are provided in the paths object which can contain the following message types:

      • uplink-message: The path to which uplink messages will be sent.
      • uplink-normalized: The path to which normalized uplink payloads will be sent.
      • join-accept: The path to which join accept messages will be sent.
      • downlink-ack: The path to which downlink acknowledgements will be sent.
      • downlink-nack: The path to which downlink not-acknowledged messages will be sent.
      • downlink-sent: The path to which downlink sent will be sent.
      • downlink-failed: The path to which downlink failures will be sent.
      • downlink-queued: The path to which downlink queued status will be sent.
      • downlink-queue-invalidated: The path to which downlink queue invalidated event will be sent. This is only used when the upstream platform carries out LoRaWAN® FRMPayload encryption.
      • location-solved: The path to which the location of the device will be sent when resolved.
      • service-data: The path to which the data from integrations is sent. Data from services such as LoRa Cloud DAS and GLS will be sent here, for example.

      Note:

      The URL (base-url) and all paths can contain template fields.

      Not all of the messages types must be handled by the service. By omitting the field in the paths object, the message type will be disabled in the instantiated webhook configuration.

      Field Mask

      Field mask can be configured by providing field paths as a list named field-mask in the body of the webhook template and contain the following paths:

      correlation_ids
      end_device_ids
      end_device_ids.application_ids
      end_device_ids.application_ids.application_id
      end_device_ids.dev_addr
      end_device_ids.dev_eui
      end_device_ids.device_id
      end_device_ids.join_eui
      received_at
      simulated
      up
      up.downlink_ack
      up.downlink_ack.class_b_c
      up.downlink_ack.class_b_c.absolute_time
      up.downlink_ack.class_b_c.gateways
      up.downlink_ack.confirmed
      up.downlink_ack.correlation_ids
      up.downlink_ack.decoded_payload
      up.downlink_ack.decoded_payload_warnings
      up.downlink_ack.f_cnt
      up.downlink_ack.f_port
      up.downlink_ack.frm_payload
      up.downlink_ack.priority
      up.downlink_ack.session_key_id
      up.downlink_failed
      up.downlink_failed.downlink
      up.downlink_failed.downlink.class_b_c
      up.downlink_failed.downlink.class_b_c.absolute_time
      up.downlink_failed.downlink.class_b_c.gateways
      up.downlink_failed.downlink.confirmed
      up.downlink_failed.downlink.correlation_ids
      up.downlink_failed.downlink.decoded_payload
      up.downlink_failed.downlink.decoded_payload_warnings
      up.downlink_failed.downlink.f_cnt
      up.downlink_failed.downlink.f_port
      up.downlink_failed.downlink.frm_payload
      up.downlink_failed.downlink.priority
      up.downlink_failed.downlink.session_key_id
      up.downlink_failed.error
      up.downlink_failed.error.attributes
      up.downlink_failed.error.cause
      up.downlink_failed.error.cause.attributes
      up.downlink_failed.error.cause.correlation_id
      up.downlink_failed.error.cause.message_format
      up.downlink_failed.error.cause.name
      up.downlink_failed.error.cause.namespace
      up.downlink_failed.error.code
      up.downlink_failed.error.correlation_id
      up.downlink_failed.error.details
      up.downlink_failed.error.message_format
      up.downlink_failed.error.name
      up.downlink_failed.error.namespace
      up.downlink_nack
      up.downlink_nack.class_b_c
      up.downlink_nack.class_b_c.absolute_time
      up.downlink_nack.class_b_c.gateways
      up.downlink_nack.confirmed
      up.downlink_nack.correlation_ids
      up.downlink_nack.decoded_payload
      up.downlink_nack.decoded_payload_warnings
      up.downlink_nack.f_cnt
      up.downlink_nack.f_port
      up.downlink_nack.frm_payload
      up.downlink_nack.priority
      up.downlink_nack.session_key_id
      up.downlink_queue_invalidated
      up.downlink_queue_invalidated.downlinks
      up.downlink_queue_invalidated.last_f_cnt_down
      up.downlink_queue_invalidated.session_key_id
      up.downlink_queued
      up.downlink_queued.class_b_c
      up.downlink_queued.class_b_c.absolute_time
      up.downlink_queued.class_b_c.gateways
      up.downlink_queued.confirmed
      up.downlink_queued.correlation_ids
      up.downlink_queued.decoded_payload
      up.downlink_queued.decoded_payload_warnings
      up.downlink_queued.f_cnt
      up.downlink_queued.f_port
      up.downlink_queued.frm_payload
      up.downlink_queued.priority
      up.downlink_queued.session_key_id
      up.downlink_sent
      up.downlink_sent.class_b_c
      up.downlink_sent.class_b_c.absolute_time
      up.downlink_sent.class_b_c.gateways
      up.downlink_sent.confirmed
      up.downlink_sent.correlation_ids
      up.downlink_sent.decoded_payload
      up.downlink_sent.decoded_payload_warnings
      up.downlink_sent.f_cnt
      up.downlink_sent.f_port
      up.downlink_sent.frm_payload
      up.downlink_sent.priority
      up.downlink_sent.session_key_id
      up.join_accept
      up.join_accept.app_s_key
      up.join_accept.app_s_key.encrypted_key
      up.join_accept.app_s_key.kek_label
      up.join_accept.app_s_key.key
      up.join_accept.invalidated_downlinks
      up.join_accept.pending_session
      up.join_accept.received_at
      up.join_accept.session_key_id
      up.location_solved
      up.location_solved.attributes
      up.location_solved.location
      up.location_solved.location.accuracy
      up.location_solved.location.altitude
      up.location_solved.location.latitude
      up.location_solved.location.longitude
      up.location_solved.location.source
      up.location_solved.service
      up.service_data
      up.service_data.data
      up.service_data.service
      up.uplink_message
      up.uplink_message.app_s_key
      up.uplink_message.app_s_key.encrypted_key
      up.uplink_message.app_s_key.kek_label
      up.uplink_message.app_s_key.key
      up.uplink_message.confirmed
      up.uplink_message.consumed_airtime
      up.uplink_message.decoded_payload
      up.uplink_message.decoded_payload_warnings
      up.uplink_message.normalized_payload
      up.uplink_message.normalized_payload_warnings
      up.uplink_message.f_cnt
      up.uplink_message.f_port
      up.uplink_message.frm_payload
      up.uplink_message.last_a_f_cnt_down
      up.uplink_message.locations
      up.uplink_message.network_ids
      up.uplink_message.network_ids.cluster_address
      up.uplink_message.network_ids.cluster_id
      up.uplink_message.network_ids.net_id
      up.uplink_message.network_ids.tenant_address
      up.uplink_message.network_ids.tenant_id
      up.uplink_message.received_at
      up.uplink_message.rx_metadata
      up.uplink_message.session_key_id
      up.uplink_message.settings
      up.uplink_message.settings.coding_rate
      up.uplink_message.settings.concentrator_timestamp
      up.uplink_message.settings.data_rate
      up.uplink_message.settings.data_rate.modulation
      up.uplink_message.settings.data_rate.modulation.fsk
      up.uplink_message.settings.data_rate.modulation.fsk.bit_rate
      up.uplink_message.settings.data_rate.modulation.lora
      up.uplink_message.settings.data_rate.modulation.lora.bandwidth
      up.uplink_message.settings.data_rate.modulation.lora.spreading_factor
      up.uplink_message.settings.data_rate.modulation.lrfhss
      up.uplink_message.settings.data_rate.modulation.lrfhss.coding_rate
      up.uplink_message.settings.data_rate.modulation.lrfhss.modulation_type
      up.uplink_message.settings.data_rate.modulation.lrfhss.operating_channel_width
      up.uplink_message.settings.downlink
      up.uplink_message.settings.downlink.antenna_index
      up.uplink_message.settings.downlink.invert_polarization
      up.uplink_message.settings.downlink.tx_power
      up.uplink_message.settings.enable_crc
      up.uplink_message.settings.frequency
      up.uplink_message.settings.time
      up.uplink_message.settings.timestamp
      up.uplink_message.version_ids
      up.uplink_message.version_ids.band_id
      up.uplink_message.version_ids.brand_id
      up.uplink_message.version_ids.firmware_version
      up.uplink_message.version_ids.hardware_version
      up.uplink_message.version_ids.model_id
      up.uplink_message.version_ids.serial_number
      up.uplink_message.version_ids.vendor_id
      up.uplink_message.version_ids.vendor_profile_id
      up.uplink_normalized
      up.uplink_normalized.confirmed
      up.uplink_normalized.consumed_airtime
      up.uplink_normalized.normalized_payload
      up.uplink_normalized.normalized_payload_warnings
      up.uplink_normalized.f_cnt
      up.uplink_normalized.f_port
      up.uplink_normalized.frm_payload
      up.uplink_normalized.locations
      up.uplink_normalized.network_ids
      up.uplink_normalized.network_ids.cluster_address
      up.uplink_normalized.network_ids.cluster_id
      up.uplink_normalized.network_ids.net_id
      up.uplink_normalized.network_ids.tenant_address
      up.uplink_normalized.network_ids.tenant_id
      up.uplink_normalized.received_at
      up.uplink_normalized.rx_metadata
      up.uplink_normalized.session_key_id
      up.uplink_normalized.settings
      up.uplink_normalized.settings.coding_rate
      up.uplink_normalized.settings.concentrator_timestamp
      up.uplink_normalized.settings.data_rate
      up.uplink_normalized.settings.data_rate.modulation
      up.uplink_normalized.settings.data_rate.modulation.fsk
      up.uplink_normalized.settings.data_rate.modulation.fsk.bit_rate
      up.uplink_normalized.settings.data_rate.modulation.lora
      up.uplink_normalized.settings.data_rate.modulation.lora.bandwidth
      up.uplink_normalized.settings.data_rate.modulation.lora.spreading_factor
      up.uplink_normalized.settings.data_rate.modulation.lrfhss
      up.uplink_normalized.settings.data_rate.modulation.lrfhss.coding_rate
      up.uplink_normalized.settings.data_rate.modulation.lrfhss.modulation_type
      up.uplink_normalized.settings.data_rate.modulation.lrfhss.operating_channel_width
      up.uplink_normalized.settings.downlink
      up.uplink_normalized.settings.downlink.antenna_index
      up.uplink_normalized.settings.downlink.invert_polarization
      up.uplink_normalized.settings.downlink.tx_power
      up.uplink_normalized.settings.enable_crc
      up.uplink_normalized.settings.frequency
      up.uplink_normalized.settings.time
      up.uplink_normalized.settings.timestamp
      up.uplink_normalized.version_ids
      up.uplink_normalized.version_ids.band_id
      up.uplink_normalized.version_ids.brand_id
      up.uplink_normalized.version_ids.firmware_version
      up.uplink_normalized.version_ids.hardware_version
      up.uplink_normalized.version_ids.model_id
      up.uplink_normalized.version_ids.serial_number
      up.uplink_normalized.version_ids.vendor_id
      up.uplink_normalized.version_ids.vendor_profile_id
      
      ← Webhook Templates Instantiation →

      On this page

      • Service Description
      • Template Fields
      • Endpoint
      • Field Mask

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories