docs/1.7/api/event/index.html - gerrit/www.eclipse.org/hono - Git at Google

 <!DOCTYPE html>
 <html lang="1.7" class="js csstransforms3d">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="Hugo 0.81.0" />
     <meta name="description" content="A set of micro-services for connecting millions of devices.">
 <meta name="author" content="The Eclipse Hono Project">

     <link rel="apple-touch-icon" sizes="180x180" href="/hono/docs/favicon/apple-touch-icon.png">
 <link rel="icon" type="image/png" sizes="48x48" href="/hono/docs/favicon/favicon-48x48.png">
 <link rel="icon" type="image/png" sizes="32x32" href="/hono/docs/favicon/favicon-32x32.png">
 <link rel="icon" type="image/png" sizes="16x16" href="/hono/docs/favicon/favicon-16x16.png">
 <link rel="manifest" href="/hono/docs/favicon/site.webmanifest">
 <link rel="mask-icon" href="/hono/docs/favicon/safari-pinned-tab.svg" color="#5bbad5">
 <link rel="shortcut icon" href="/hono/docs/favicon/favicon.ico">
 <meta name="msapplication-TileColor" content="#da532c">
 <meta name="msapplication-config" content="/hono/docs/favicon/browserconfig.xml">
 <meta name="theme-color" content="#ffffff">

     <title>Event API Specification :: Eclipse Hono&trade; Vers.: 1.7</title>


     <link href="/hono/docs/css/nucleus.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/fontawesome-all.min.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/hybrid.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/featherlight.min.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/auto-complete.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/theme.css?1626138719" rel="stylesheet">
     <link href="/hono/docs/css/hugo-theme.css?1626138719" rel="stylesheet">

     <link href="/hono/docs/css/theme-hono.css?1626138719" rel="stylesheet">

     <link href="/hono/docs/css/hono.css?1626138719" rel="stylesheet">

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138719"></script>

     <style>
       :root #header + #content > #left > #rlblock_left{
           display:none !important;
       }

         :not(pre) > code + span.copy-to-clipboard {
             display: none;
         }

     </style>

 <link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css">


 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:site" content="@EclipseHono">
 <meta name="twitter:title" content="Event API Specification :: Eclipse Hono&amp;trade; Vers.: 1.7">
 <meta name="twitter:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png">
 <meta name="twitter:description" content="A set of micro-services for connecting millions of devices.">


 <meta property="og:title" content="Event API Specification :: Eclipse Hono&amp;trade; Vers.: 1.7" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.7/api/event//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.7/api/event/">
     <nav id="sidebar" class="">


   <div id="header-wrapper">
     <div id="header">
       <a href="https://www.eclipse.org/hono/">
     <img src="/hono/docs/images/HONO-Logo_Bild-Wort_quer-w-310x120px.svg" alt="Hono logo" class="logo-img">
 </a>

     </div>

         <div class="searchbox">
     <label for="search-by"><i class="fas fa-search"></i></label>
     <input data-search-input id="search-by" type="search" placeholder="Search...">
     <span data-search-clear=""><i class="fas fa-times"></i></span>
 </div>

 <script type="text/javascript" src="/hono/docs/js/lunr.min.js?1626138719"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138719"></script>
 <script type="text/javascript">

         var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.7";

 </script>
 <script type="text/javascript" src="/hono/docs/js/search.js?1626138719"></script>


   </div>

     <div class="highlightable">
     <ul class="topics">


     <li data-nav-id="/hono/docs/1.7/concepts/" title="Concepts" class="dd-item


         ">
       <a href="/hono/docs/1.7/concepts/">
           <i class="far fa-lightbulb"></i> Concepts

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/concepts/device-identity/" title="Device Identity" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/device-identity/">
         Device Identity

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/tenancy/" title="Multi-Tenancy" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/tenancy/">
         Multi-Tenancy

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/device-provisioning/" title="Device Provisioning" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/device-provisioning/">
         Device Provisioning

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/connecting-devices/" title="Connecting Devices" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/connecting-devices/">
         Connecting Devices

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/device-notifications/" title="Device Notifications" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/device-notifications/">
         Device Notifications

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/command-and-control/" title="Command &amp; Control" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/command-and-control/">
         Command &amp; Control

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/resource-limits/" title="Resource limits" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/resource-limits/">
         Resource limits

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/concepts/connection-events/" title="Connection Events" class="dd-item ">
         <a href="/hono/docs/1.7/concepts/connection-events/">
         Connection Events

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/user-guide/" title="User Guide" class="dd-item


         ">
       <a href="/hono/docs/1.7/user-guide/">
           <i class="fas fa-book-reader"></i> User Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/user-guide/mongodb-based-device-registry/" title="MongoDB Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/mongodb-based-device-registry/">
         MongoDB Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/jdbc-based-device-registry/" title="JDBC Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/jdbc-based-device-registry/">
         JDBC Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/file-based-device-registry/" title="File Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/file-based-device-registry/">
         File Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/http-adapter/">
         HTTP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/mqtt-adapter/">
         MQTT Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/amqp-adapter/">
         AMQP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/coap-adapter/">
         CoAP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/kura-adapter/">
         Kura Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/user-guide/sigfox-adapter/">
         Sigfox Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/admin-guide/" title="Admin Guide" class="dd-item


         ">
       <a href="/hono/docs/1.7/admin-guide/">
           <i class="fas fa-sliders-h"></i> Admin Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/admin-guide/common-config/" title="Common Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/common-config/">
         Common Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/auth-server-config/">
         Auth Server Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/mongodb-device-registry-config/" title="MongoDB Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/mongodb-device-registry-config/">
         MongoDB Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/jdbc-device-registry-config/" title="JDBC Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/jdbc-device-registry-config/">
         JDBC Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/file-based-device-registry-config/" title="File Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/file-based-device-registry-config/">
         File Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/command-router-config/" title="Configuring the Command Router Service" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/command-router-config/">
         Command Router Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/device-connection-config/">
         Device Connection Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/http-adapter-config/">
         HTTP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/mqtt-adapter-config/">
         MQTT Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/amqp-adapter-config/">
         AMQP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/coap-adapter-config/" title="CoAP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/coap-adapter-config/">
         CoAP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/kura-adapter-config/">
         Kura Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/hono-client-configuration/">
         Hono Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/hono-kafka-client-configuration/" title="Hono Kafka Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/hono-kafka-client-configuration/">
         Hono Kafka Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/amqp-network-config/">
         AMQP 1.0 Messaging Network Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/secure_communication/" title="Secure Communication" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/secure_communication/">
         Secure Communication

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/admin-guide/monitoring-tracing-config/" title="Monitoring &amp; Tracing" class="dd-item ">
         <a href="/hono/docs/1.7/admin-guide/monitoring-tracing-config/">
         Monitoring &amp; Tracing

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/dev-guide/" title="Developer Guide" class="dd-item


         ">
       <a href="/hono/docs/1.7/dev-guide/">
           <i class="fas fa-tools"></i> Developer Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/dev-guide/building_hono/" title="Building from Source" class="dd-item ">
         <a href="/hono/docs/1.7/dev-guide/building_hono/">
         Building from Source

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item ">
         <a href="/hono/docs/1.7/dev-guide/amqp_adapter_client/">
         AMQP Adapter Client for Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item ">
         <a href="/hono/docs/1.7/dev-guide/java_client_consumer/">
         Consuming Messages from Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item ">
         <a href="/hono/docs/1.7/dev-guide/custom_http_adapter/">
         Implement a Custom Hono HTTP Protocol Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/api/" title="API" class="dd-item
         parent


         ">
       <a href="/hono/docs/1.7/api/">
           &nbsp;<i class='fas fa-plug'></i>&nbsp;API

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/api/telemetry/" title="Telemetry API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/telemetry/">
         Telemetry API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/event/" title="Event API Specification" class="dd-item active">
         <a href="/hono/docs/1.7/api/event/">
         Event API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/command-and-control/" title="Command &amp; Control API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/command-and-control/">
         Command &amp; Control API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/kafka-api/" title="Kafka-based APIs" class="dd-item ">
         <a href="/hono/docs/1.7/api/kafka-api/">
         Kafka-based APIs

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/telemetry-kafka/" title="Telemetry API for Kafka Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/telemetry-kafka/">
         Telemetry API for Kafka

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/event-kafka/" title="Event API for Kafka Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/event-kafka/">
         Event API for Kafka

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/command-and-control-kafka/" title="Command &amp; Control API for Kafka Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/command-and-control-kafka/">
         Command &amp; Control API for Kafka

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/tenant/" title="Tenant API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/tenant/">
         Tenant API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/command-router/" title="Command Router API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/command-router/">
         Command Router API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/device-connection/" title="Device Connection API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/device-connection/">
         Device Connection API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/device-registration/" title="Device Registration API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/device-registration/">
         Device Registration API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/credentials/" title="Credentials API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/credentials/">
         Credentials API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/authentication/" title="Authentication API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/authentication/">
         Authentication API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/management/" title="Device Registry Management API Specification" class="dd-item ">
         <a href="/hono/docs/1.7/api/management/">
         Device Registry Management API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/api/metrics/" title="Metrics" class="dd-item ">
         <a href="/hono/docs/1.7/api/metrics/">
         Metrics

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/deployment/" title="Deployment" class="dd-item


         ">
       <a href="/hono/docs/1.7/deployment/">
           <i class="fas fa-shipping-fast"></i> Deployment

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item ">
         <a href="/hono/docs/1.7/deployment/helm-based-deployment/">
         Helm based Deployment

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/deployment/openshift/" title="OpenShift / OKD" class="dd-item ">
         <a href="/hono/docs/1.7/deployment/openshift/">
         OpenShift / OKD

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item ">
         <a href="/hono/docs/1.7/deployment/create-kubernetes-cluster/">
         Setting up a Kubernetes Cluster

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item ">
         <a href="/hono/docs/1.7/deployment/resource-limitation/">
         Limiting Resource Usage

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.7/architecture/" title="Architecture" class="dd-item


         ">
       <a href="/hono/docs/1.7/architecture/">
           <i class="fas fa-landmark"></i> Architecture

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.7/architecture/component-view/" title="Component View" class="dd-item ">
         <a href="/hono/docs/1.7/architecture/component-view/">
         Component View

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.7/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.7/architecture/auth/">
         Authentication/Authorization

         </a>
     </li>


         </ul>

     </li>


     </ul>


       <section id="shortcuts">
         <h3></h3>
         <ul>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/" title="Hono&#39;s Homepage"><i class='fas fa-home'></i> Hono Home</a>
               </li>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/getting-started/" title="Getting started with Eclipse Hono"><i class='fas fa-plane-departure'></i> Getting Started</a>
               </li>

         </ul>
       </section>


     <section id="prefooter">
       <hr/>
       <ul>

         <li>
           <div id="select-box-wrapper">
           <div id="select-box">
           <a class="padding">
             Version:&nbsp;
           <div class="select-style">
             <select id="select-language" onchange="location = this.value;">


                       <option id="stable" value="https://www.eclipse.org/hono/docs/api/event/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/api/event/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/api/event/" selected>1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/api/event/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/api/event/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/api/event/">1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/api/event/">1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/api/event/">1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/api/event/">1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/api/event/">1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/api/event/">dev</option>


         </select>
         <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
           width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve">
           <g>
             <g id="arrow-drop-down">
               <polygon points="0,63.75 127.5,191.25 255,63.75 		" />
             </g>
           </g>
         </svg>
         </div>
         </a>
         </div>
         </div>
         </li>


       </ul>
     </section>

     <section id="footer">


 <p>&copy; 2021 <a href="https://www.eclipse.org/hono/">The Eclipse Hono Project</a></p>

 <p>
     Documentation built with
     <a href="https://gohugo.io/" target="_blank">Hugo</a>
     using the
     <a href="https://github.com/matcornic/hugo-theme-learn" target="_blank">Learn</a> theme.
 </p>

 <div class="eclipse-logo">
     <a href="https://www.eclipse.org" target="_blank">
         <img src="https://www.eclipse.org/hono/docs/images/eclipse_foundation_logo.svg"/>
     </a>
 </div>

     </section>
   </div>
 </nav>


         <section id="body">
         <div id="overlay"></div>


     <div class="old-version-hint">
         <p>This page refers to version <em>1.7</em>.
             You might want to use the <a href="https://www.eclipse.org/hono/docs/">current stable</a> version.
         </p>
     </div>


         <div class="padding highlightable">

               <div>
                 <div id="top-bar">


                   <div id="top-github-link">
                     <a class="github-link" title='Edit this page' href="https://github.com/eclipse/hono/edit/master/site/documentation/content/api/event/index.md" target="blank">
                       <i class="fas fa-code-branch"></i>
                       <span id="top-github-link-text">Edit this page</span>
                     </a>
                   </div>


                 <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
                     <span id="sidebar-toggle-span">
                         <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
                           <i class="fas fa-bars"></i>
                         </a>
                     </span>

                   <span id="toc-menu"><i class="fas fa-list-alt"></i></span>

                   <span class="links">


             <a href='/hono/docs/1.7/'>Documentation</a> > <a href='/hono/docs/1.7/api/'>API</a> > Event API Specification


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#southbound-operations">Southbound Operations</a>
       <ul>
         <li><a href="#forward-event">Forward Event</a></li>
       </ul>
     </li>
     <li><a href="#northbound-operations">Northbound Operations</a>
       <ul>
         <li><a href="#receive-events">Receive Events</a></li>
       </ul>
     </li>
     <li><a href="#well-known-event-message-types">Well-known Event Message Types</a>
       <ul>
         <li><a href="#empty-notification">Empty Notification</a></li>
         <li><a href="#connection-event">Connection Event</a></li>
         <li><a href="#device-provisioning-notification">Device Provisioning Notification</a></li>
       </ul>
     </li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Event API Specification
             </h1>


 <p>The <em>Event</em> API is used by <em>Protocol Adapters</em> to send event messages downstream.
 <em>Business Applications</em> and other consumers use the API to receive messages published by devices belonging to a particular tenant.</p>
 <p>The Event API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use <em>AMQP</em> when referring to AMQP 1.0.</p>
 <h2 id="southbound-operations">Southbound Operations</h2>
 <p>The following operations can be used by <em>Protocol Adapters</em> to forward event messages received from devices to downstream consumers like <em>Business Applications</em>.</p>
 <h3 id="forward-event">Forward Event</h3>
 <p><strong>Preconditions</strong></p>
 <ol>
 <li>Adapter has established an AMQP connection with the AMQP Messaging Network.</li>
 <li>Adapter has established an AMQP link in role <em>sender</em> with the AMQP Messaging Network using target address <code>event/${tenant_id}</code> where <code>${tenant_id}</code> is the ID of the tenant that the client wants to upload event messages for.</li>
 <li>The device for which the adapter wants to send an event has been registered (see <a href="/hono/docs/1.7/api/device-registration/">Device Registration API</a>).</li>
 </ol>
 <p>Hono supports <em>AT LEAST ONCE</em> delivery of <em>Event</em> messages only. A client therefore MUST use <code>unsettled</code> for the <em>snd-settle-mode</em> and <code>first</code> for the <em>rcv-settle-mode</em> fields of its <em>attach</em> frame during link establishment. All other combinations are not supported by Hono and may result in the termination of the link or connection (depending on the configuration of the AMQP Messaging Network).</p>
 <p>The AMQP messages used to forward events to the AMQP Messaging Network MUST have their <em>durable</em> property set to <code>true</code>. The AMQP Messaging Network is expected to write such messages to a persistent store before settling the transfer with the <code>accepted</code> outcome.</p>
 <p><strong>Message Flow</strong></p>
 <p>The following sequence diagram illustrates the flow of messages involved in the <em>MQTT Adapter</em> forwarding an event to the downstream AMQP Messaging Network.</p>
 <figure>
     <img src="forward.svg"/> <figcaption>
             <h4>Forward event flow</h4>
         </figcaption>
 </figure>

 <ol>
 <li><em>Device</em> <code>4711</code> publishes an event using MQTT QoS 1.
 <ol>
 <li><em>MQTT Adapter</em> transfers data to <em>AMQP 1.0 Messaging Network</em>.</li>
 <li><em>AMQP 1.0 Messaging Network</em> acknowledges reception of the message.</li>
 <li><em>MQTT Adapter</em> acknowledges the reception of the message to the <em>Device</em>.</li>
 </ol>
 </li>
 </ol>
 <p>When the AMQP Messaging Network fails to settle the transfer of an event message or settles the transfer with any other outcome than <code>accepted</code>, the protocol adapter MUST NOT try to re-send such rejected messages but MUST indicate the failed transfer to the device if the transport protocol provides means to do so.</p>
 <p><strong>Message Format</strong></p>
 <p>See <a href="/hono/docs/1.7/api/telemetry/#forward-telemetry-data">Telemetry API</a> for definition of message format.</p>
 <h2 id="northbound-operations">Northbound Operations</h2>
 <h3 id="receive-events">Receive Events</h3>
 <p>Hono delivers messages containing events reported by a particular device in the same order that they have been received in (using the <a href="#forward-event">Forward Event</a> operation).</p>
 <p>Hono supports multiple non-competing <em>Business Application</em> consumers of event messages for a given tenant. Hono allows each <em>Business Application</em> to have multiple competing consumers for event messages for a given tenant to share the load of processing the messages.</p>
 <p><strong>Preconditions</strong></p>
 <ol>
 <li>Client has established an AMQP connection with Hono.</li>
 <li>Client has established an AMQP link in role <em>receiver</em> with Hono using source address <code>event/${tenant_id}</code> where <code>${tenant_id}</code> represents the ID of the tenant the client wants to retrieve event messages for.</li>
 </ol>
 <p>Hono supports <em>AT LEAST ONCE</em> delivery of <em>Event</em> messages only. A client therefore MUST use <code>unsettled</code> for the <em>snd-settle-mode</em> and <code>first</code> for the <em>rcv-settle-mode</em> fields of its <em>attach</em> frame during link establishment. All other combinations are not supported by Hono and result in the termination of the link.</p>
 <p><strong>Message Flow</strong></p>
 <p>The following sequence diagram illustrates the flow of messages involved in a <em>Business Application</em> receiving an event message from Hono.</p>
 <figure>
     <img src="consume.svg"/> <figcaption>
             <h4>Receive event data flow (success)</h4>
         </figcaption>
 </figure>

 <ol>
 <li><em>AMQP 1.0 Messaging Network</em> delivers event message to <em>Business Application</em>.
 <ol>
 <li><em>Business Application</em> acknowledges reception of message.</li>
 </ol>
 </li>
 </ol>
 <p><strong>Message Format</strong></p>
 <p>See <a href="/hono/docs/1.7/api/telemetry/#forward-telemetry-data">Telemetry API</a> for definition of message format.</p>
 <h2 id="well-known-event-message-types">Well-known Event Message Types</h2>
 <p>Hono defines several <em>well-known</em> event types which have specific semantics. Events of these types are identified by means of the AMQP message&rsquo;s <em>content-type</em>.</p>
 <h3 id="empty-notification">Empty Notification</h3>
 <p>An AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.</p>
 <p>The AMQP 1.0 properties an event sender needs to set for an <em>empty notification</em> event are defined in the <a href="/hono/docs/1.7/api/telemetry/"><em>Telemetry API</em></a>.</p>
 <p>The relevant properties are listed again in the following table:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>content-type</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>symbol</em></td>
 <td style="text-align:left">MUST be set to <em>application/vnd.eclipse-hono-empty-notification</em></td>
 </tr>
 <tr>
 <td style="text-align:left"><em>ttd</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>int</em></td>
 <td style="text-align:left">The <em>time &lsquo;til disconnect</em> as described in the <a href="/hono/docs/1.7/api/telemetry/"><em>Telemetry API</em></a>.</td>
 </tr>
 </tbody>
 </table>
 <p><strong>NB</strong> An empty notification can be used to indicate to a <em>Business Application</em> that a device is currently ready to receive an upstream message by setting the <em>ttd</em> property. <em>Backend Applications</em> may use this information to determine the time window during which the device will be able to receive a command.</p>
 <h3 id="connection-event">Connection Event</h3>
 <p>Protocol Adapters may send this type of event to indicate that a connection with a device has
 been established or has ended. Note that such events can only be sent for authenticated devices,
 though, because an event is always scoped to a tenant and the tenant of a device is
 established as part of the authentication process.</p>
 <p>The AMQP message for a connection event MUST contain the following properties in addition to the standard event properties:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>content-type</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>symbol</em></td>
 <td style="text-align:left">Must be set to  <em>application/vnd.eclipse-hono-dc-notification+json</em></td>
 </tr>
 <tr>
 <td style="text-align:left"><em>device_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The ID of the authenticated device</td>
 </tr>
 </tbody>
 </table>
 <p>Each connection event&rsquo;s payload MUST contain a UTF-8 encoded string representation of a single JSON object with the following fields:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>cause</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The cause of the connection event. MUST be set to either <code>connected</code> or <code>disconnected</code>.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>remote-id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">An identifier of the device that is the subject of this event, e.g. an IP address:port, client id etc. The format and semantics of this identifier is specific to the protocol adapter and the transport protocol it supports.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>source</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The type name of the protocol adapter reporting the event, e.g. <code>hono-mqtt</code>.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>data</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>object</em></td>
 <td style="text-align:left">An arbitrary JSON object which may contain additional information about the occurrence of the event.</td>
 </tr>
 </tbody>
 </table>
 <p>The example below might be used by the MQTT adapter to indicate that a connection with a device using client identifier <code>mqtt-client-id-1</code> has been established:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
   <span style="color:#f92672">&#34;cause&#34;</span>: <span style="color:#e6db74">&#34;connected&#34;</span>,
   <span style="color:#f92672">&#34;remote-id&#34;</span>: <span style="color:#e6db74">&#34;mqtt-client-id-1&#34;</span>,
   <span style="color:#f92672">&#34;source&#34;</span>: <span style="color:#e6db74">&#34;hono-mqtt&#34;</span>,
   <span style="color:#f92672">&#34;data&#34;</span>: {
     <span style="color:#f92672">&#34;foo&#34;</span>: <span style="color:#e6db74">&#34;bar&#34;</span>
   }
 }
 </code></pre></div><h3 id="device-provisioning-notification">Device Provisioning Notification</h3>
 <p>Device registries may send this event to convey provisioning related changes regarding a device. This may be used as a hook for
 northbound applications if further application specific logic should be implemented upon provisioning changes.</p>
 <p>An AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.</p>
 <p>The relevant properties are listed again in the following table:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>content-type</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>symbol</em></td>
 <td style="text-align:left">MUST be set to <em>application/vnd.eclipse-hono-device-provisioning-notification</em></td>
 </tr>
 <tr>
 <td style="text-align:left"><em>hono_registration_status</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">Contains NEW if the device has been newly provisioned.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>tenant_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The tenant id denoting the tenant of the device.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>device_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The id of the device.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>gateway_id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">This property contains a value only if the device&rsquo;s registration status has been changed by a gateway acting on behalf of the device. In such a case, the property contains the identifier of the gateway, otherwise the property will not be included.</td>
 </tr>
 </tbody>
 </table>

 <footer class="footline">

 </footer>


         </div>


       </div>

     <div id="navigation">


     </div>

     </section>

     <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
       <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
     </div>
     <script src="/hono/docs/js/clipboard.min.js?1626138719"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138719"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138719"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138719"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138719"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138719"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138720"></script>
     <script src="/hono/docs/js/learn.js?1626138720"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138720"></script>

     <link href="/hono/docs/mermaid/mermaid.css?1626138720" rel="stylesheet" />
     <script src="/hono/docs/mermaid/mermaid.js?1626138720"></script>
     <script>
         mermaid.initialize({ startOnLoad: true });
     </script>


 <script>
     (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
             new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
         j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
         'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
     })(window,document,'script','dataLayer','GTM-5WLCZXC');
 </script>


 <script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>

   </body>
 </html>