Events

Voxie has standardized on CloudEvents as the method of defining data across event-driven communication. We see this as a strong way forward towards interoperability with other cloud providers and tools including Azure and Google Cloud who provide native support.

You can find more information regarding the techincal spec for CloudEvents in the cloudevents/spec repository on Github. Our CloudEvents will always have the specversion, id, source, type, datacontenttype, dataschema, time, and data attributes set. Moreover, datacontenttype will always be set to application/json and dataschema to a URL for the JSON Schema describing the data field. We are compatible with all JSON Schema versions from draft 4 upwards. Finally, note that the id field can be used to uniquely identify any event - a stronger property than required by the CloudEvent specificaition which only mandates uniqueness within each producer.

Delivery

Events matching the filters for a subscription are delivered to the sink via HTTP POST requests. We require sinks to use the https scheme and support HTTP 1.1 or 2 with TLS 1.2 or 1.3. We deliver our events using the structured content mode and sign our requests according to draft-ietf-httpbis-message-signatures-05 using the ecdsa-p256-sha256 algorithm. The keyid field of the signature input will be a URL identifying the public signing key. An example delivery HTTP request (with the signature stubbed out) is provided below:

POST /your-endpoint
Host: example.com
Content-Type: application/cloudevents+json; charset=UTF-8
Content-Length: 604
Date: Tue, 03 Aug 2021 15:21:35 GMT
Digest: SHA-256=4pdKlQEUk/SZTKbl/ssviY2VfLkjoZ6/Ht5Sh4FLBz4=
User-Agent: Voxie/1.0
Signature-Input: sig1=("date" "content-type" "digest" "content-length" "user-agent" "@request-target");alg="ecdsa-p256-sha256";keyid="https://registry.voxie.com/keys/outbound-hooks/eabdc48d.pem";nonce=27fde337ab04852f23c8eccf3bc4e8a4
Signature:sig1=:...:
{
  "specversion": "1.0",
  "id": "1wDreVpnbNWFKJtyLfvGENtUzqk",
  "source": "voxie/core",
  "type": "com.voxie.contact.created",
  "datacontenttype": "application/json",
  "dataschema": "https://registry.voxie.com/schema/v1/contact/created.json",
  "time": "2021-08-03T15:21:35Z",
  "comvoxiepublic": true,
  "comvoxieteam": 1,
  "data": {
    "at": "2021-08-03T15:21:35Z",
    "team_id": 1,
    "contact_id": 288331,
    "contact_phone_number": "+17092080726",
    "contact_email": "contact@example.com",
    "contact_first_name": "Example",
    "contact_last_name": "Contact"
  }
}

Note that events will be delivered using "at least once" semantics and as close to when they were raised as possible. This means that events may be delivered out of order or multiple times. CloudEvents can be identified by their id field. Subscribers can identify duplicates using the id attribute. Failed deliveries will be re-tried for up to 24 hours.