Publishing & subscribing messages with Cloudevents

Learn why Dapr uses CloudEvents, how they work in Dapr pub/sub, and how to create CloudEvents.

To enable message routing and provide additional context with each message, Dapr uses the CloudEvents 1.0 specification as its message format. Any message sent by an application to a topic using Dapr is automatically wrapped in a CloudEvents envelope, using the Content-Type header value for datacontenttype attribute.

Dapr uses CloudEvents to provide additional context to the event payload, enabling features like:

  • Tracing
  • Content-type for proper deserialization of event data
  • Verification of sender application

CloudEvents example

A publish operation to Dapr results in a cloud event envelope containing the following fields:

  • id
  • source
  • specversion
  • type
  • traceparent
  • traceid
  • tracestate
  • topic
  • pubsubname
  • time
  • datacontenttype (optional)

The following example demonstrates a cloud event generated by Dapr for a publish operation to the orders topic that includes a W3C traceid unique to the message, the data and the fields for the CloudEvent where the data content is serialized as JSON.

  1. {
  2.   "topic": "orders",
  3.   "pubsubname": "order_pub_sub",
  4.   "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
  5.   "tracestate": "",
  6.   "data": {
  7.     "orderId": 1
  8.   },
  9.   "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
  10.   "specversion": "1.0",
  11.   "datacontenttype": "application/json; charset=utf-8",
  12.   "source": "checkout",
  13.   "type": "com.dapr.event.sent",
  14.   "time": "2020-09-23T06:23:21Z",
  15.   "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
  16. }

As another example of a v1.0 CloudEvent, the following shows data as XML content in a CloudEvent message serialized as JSON:

  1. {
  2.     "specversion" : "1.0",
  3.     "type" : "xml.message",
  4.     "source" : "https://example.com/message",
  5.     "subject" : "Test XML Message",
  6.     "id" : "id-1234-5678-9101",
  7.     "time" : "2020-09-23T06:23:21Z",
  8.     "datacontenttype" : "text/xml",
  9.     "data" : "<note><to>User1</to><from>user2</from><message>hi</message></note>"
  10. }

Publish your own CloudEvent

If you want to use your own CloudEvent, make sure to specify the datacontenttype as application/cloudevents+json. If the CloudEvent that was authored by the app does not contain the minimum required fields in the CloudEvent specification, the message is rejected. Dapr adds the following fields to the CloudEvent if they are missing:

  • time
  • traceid
  • traceparent
  • tracestate
  • topic
  • pubsubname
  • source
  • type
  • specversion

You can add additional fields to a custom CloudEvent that are not part of the official CloudEvent specification. Dapr will pass these fields as-is.

Example

Publish a CloudEvent to the orders topic:

  1. dapr publish --publish-app-id orderprocessing --pubsub order-pub-sub --topic orders --data '{\"orderId\": \"100\"}'

Publish a CloudEvent to the orders topic:

  1. curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders -H "Content-Type: application/cloudevents+json" -d '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}'

Publish a CloudEvent to the orders topic:

  1. Invoke-RestMethod -Method Post -ContentType 'application/cloudevents+json' -Body '{"specversion" : "1.0", "type" : "com.dapr.cloudevent.sent", "source" : "testcloudeventspubsub", "subject" : "Cloud Events Test", "id" : "someCloudEventId", "time" : "2021-08-02T09:00:00Z", "datacontenttype" : "application/cloudevents+json", "data" : {"orderId": "100"}}' -Uri 'http://localhost:3601/v1.0/publish/order-pub-sub/orders'

Event deduplication

When using cloud events created by Dapr, the envelope contains an id field which can be used by the app to perform message deduplication. Dapr does not handle deduplication automatically. Dapr supports using message brokers that natively enable message deduplication.

Next steps

Last modified June 19, 2023: Merge pull request #3565 from dapr/aacrawfi/skip-secrets-close (b1763bf)