Outbound REST API

You can enable receipt of event notifications via your REST API. In order to maximum compatibility, the message format we provide for event messages we sent you is simpler than that used for the REST API messages you send us.

Configuring Outbound Event Messages

You can configure outbound REST API messages via the “REST API” page, accessible from your “Settings” page.

To enable receipt of REST API messages, simply provide a full URL to an endpoint on your infrastructure to receive the message. You can include query strings and fragments with the URL, if needed.

You can also optionally include an API key that will be embedded in the message we send you. You can use the API key as a simple authentication scheme.

Message Format

All outbound REST API messages are sent to you via HTTP POST method. The request body will be a JSON encoded payload such as that shown below:

{
    "api_key" : "<api key>",
    "event_type" : "<event type>",
    "message" : "message",
    "timestamp" : timestamp,
    "authority" : host_scheme_url,
    "path" : "path",
    "url" : "full URL"
 }

Each field is explained in Table 17.

Table 17 Outbound Message Format

Key

Type

Function

api_key

str

The API key you provide on the “REST API” page.

event_type

str

The event type. Values are the same as those listed in Table 28 for the event_type field.

message

str

An optional message included with the event.

timestamp

int

The Unix timestamp indicating when the event was detected.

authority

str

Your site’s authority. Value will be of the form “https://mysite.com”.

path

str

The path on the server to the page or endpoint that triggered the event.

url

str

The full URL to the page or endpoint that triggered the event.

Return Values

On success, we confirm that we received a 200 status. We ignore all other return data.

Note that, at this time, we do not retry the request on failure. We will likely change this in the near future.