Event Format

Owned by Aaron Harrington (Unlicensed)
Last updated: Jun 30, 2016 by Joel Edwards (Unlicensed)
2 min read

Structure

  • access_key: (Required; Hex-encoded bytes) The access component of the API key with which the client_salt and client_secret are associated.
  • client_salt: (Required; Hex-encoded bytes) The client_salt which is paired with the access_key and was used in order to derive the client_secret, which is used in turn to sign the payload, generating the Payload_HMAC header for the event request.
  • timestamp: (Required; ISO-8601 formatted with at least second-level granularity) The current timestamp.
    • This is compared with the server's current time this must be within 1 minute of server time when it is processed. This is a security measure to prevent replay attacks using an old event payload.
  • debug_directive: (Optional; Text) A directive that can be used for simple testing. Currently only one value is permitted if present.
    • echo-as-message: skips all rule evaluation and sends a message with the event as the payload.
  • event_name: (Required; Text) The name of the event which will be included in messages generated by a campaign when this was the event which caused that campaign's rules to be evaluated.
  • namespace: (Required; Text) The namespace with which this event is associated, which determines the attribute schema.
  • attributes: (Required; JSON object) Object containing namespace specific attributes. All primary key attributes must be present, or the request will be rejected.
    • The names and types of the supplied attributes must match those defined either within the namespace above, or defined as core attributes on the customer's account.
  • tags: (Optional; JSON array containing text values) Additional metadata that can be passed along in the event.

The body must be sent as UTF-8 encoded JSON.

Example

{
  "access_key": "a59f5674cd87ce2139b0d81de72bd16e",
  "client_salt": "d4d72828284c84eb9c49100a9fd07562581fdc758671e21a3c701bbeda726c0d",
  "timestamp": "2016-06-28T23:49:25.835Z",
  "event_name": "event",
  "namespace": "namespace",
  "attributes": {
    "integer_att": 3,
	"float_att": 5.67,
    "string_att": "example",
    "date_att": "2016-06-24T22:00:00.835Z",
    "boolean_att": true
  },
  "tags": [
	"tag1",
	"tag2"
  ]
}


Signing a Request

A header named Payload-HMAC must be supplied containing the hex-encoded HMAC-SHA256 of the UTF-8 encoded JSON request body and the raw (hex-decoded) bytes of the client_secret used as the HMAC key.

Example:

The above example event produces this UTF-8 encoded JSON request body (hex encoding and newlines added for readability)

7b0a2020226163636573735f6b6579223a202261353966353637346364383763
65323133396230643831646537326264313665222c0a202022636c69656e745f
73616c74223a2022643464373238323832383463383465623963343931303061
3966643037353632353831666463373538363731653231613363373031626265
6461373236633064222c0a20202274696d657374616d70223a2022323031362d
30362d32385432333a34393a32352e3833355a222c0a2020226576656e745f6e
616d65223a20226576656e74222c0a2020226e616d657370616365223a20226e
616d657370616365222c0a20202261747472696275746573223a207b0a202020
2022696e74656765725f617474223a20332c0a202022666c6f61745f61747422
3a20352e36372c0a2020202022737472696e675f617474223a20226578616d70
6c65222c0a2020202022646174655f617474223a2022323031362d30362d3234
5432323a30303a30302e3833355a222c0a2020202022626f6f6c65616e5f6174
74223a20747275650a20207d2c0a20202274616773223a205b0a202022746167
31222c0a20202274616732220a20205d0a7d

When HMAC-SHA256 is applied using client secret 2f72f5a76137f65f917c21d4a9ef3e7963b1cdd0b30778afa4e876cb2222631a as the key and the raw bytes from the above as the message, the following HMAC is produced:

01a67cb19644b6b21ce2429a53fde3ee3b801afae97a7c4943bd02f9b67313e0