• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Consul Home

API

Skip to main content
  • API
  • API Structure

  • Admin Partitions
  • Catalog
  • Cluster Peering
  • Config
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. API
  4. Events
  • Consul
  • v1.13.x
  • v1.12.x
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x

ยปEvent HTTP Endpoint

The /event endpoints fire new events and to query the available events in Consul.

Fire Event

This endpoint triggers a new user event.

MethodPathProduces
PUT/event/fire/:nameapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneevent:write

The corresponding CLI command is consul event.

Path Parameters

  • name (string: <required>) - Specifies the name of the event to fire. This name must not start with an underscore, since those are reserved for Consul internally.

Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • node (string: "") - Specifies a regular expression to filter by node name.

  • service (string: "") - Specifies a regular expression to filter by service name.

  • tag (string: "") - Specifies a regular expression to filter by tag.

Sample Payload

The body contents are opaque to Consul and become the "payload" that is passed onto the receiver of the event.

Lorem ipsum dolor sit amet, consectetur adipisicing elit...

Sample Request

$ curl \
    --request PUT \
    --data @payload \
    http://127.0.0.1:8500/v1/event/fire/my-event

Sample Response

{
  "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
  "Name": "deploy",
  "Payload": null,
  "NodeFilter": "",
  "ServiceFilter": "",
  "TagFilter": "",
  "Version": 1,
  "LTime": 0
}
  • ID is a unique identifier the newly fired event

List Events

This endpoint returns the most recent events (up to 256) known by the agent. As a consequence of how the event command works, each agent may have a different view of the events. Events are broadcast using the gossip protocol, so they have no global ordering nor do they make a promise of delivery.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/event/listapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESnonenoneevent:read

Query Parameters

  • name (string: "") - Specifies the name of the event to filter.

  • node (string: "") - Specifies a regular expression to filter by node name.

  • service (string: "") - Specifies a regular expression to filter by service name.

  • tag (string: "") - Specifies a regular expression to filter by tag.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/event/list

Sample Response

[
  {
    "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
    "Name": "deploy",
    "Payload": "MTYwOTAzMA==",
    "NodeFilter": "",
    "ServiceFilter": "",
    "TagFilter": "",
    "Version": 1,
    "LTime": 19
  }
]

Caveat

The semantics of this endpoint's blocking queries are slightly different. Most blocking queries provide a monotonic index and block until a newer index is available. This can be supported as a consequence of the total ordering of the consensus protocol. With gossip, there is no ordering, and instead X-Consul-Index maps to the newest event that matches the query.

In practice, this means the index is only useful when used against a single agent and has no meaning globally. Because Consul defines the index as being opaque, clients should not be expecting a natural ordering either.

Edit this page on GitHub

On this page

  1. Event HTTP Endpoint
  2. Fire Event
  3. List Events
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)