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
  • Deduplication by message Id
  • Content-type for proper deserialization of event data

CloudEvents example

Dapr implements the following CloudEvents fields when creating a message topic.

  • id
  • source
  • specversion
  • type
  • traceparent
  • time
  • datacontenttype (optional)

The following example demonstrates an orders topic message sent by Dapr 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.

Example

Publish a CloudEvent to the orders topic:

  1. dapr publish --publish-app-id orderprocessing --pubsub order-pub-sub --topic orders --data '{"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. 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'

Next steps

Last modified October 5, 2022: Include the newly added `time` field for CloudEvent (#2858) (da492c4d)