Skip to content

Callback

It is possible to configure MyPup to send updates when something has changed. These updates are send to a single URL using HTTP POST requests.

Ensure Successfull Delivery

When receiving a callback message, you must always respond with a HTTP 2xx code when the message is received at your end. Any other errors or failures will queue the message for a later time. Failed messages are retried indefinitely and are only discarded upon successful delivery.

Configure Callback

To configure the callback url make a request to /v1/Platform/ConfigureCallback, for example when your service or application starts.

When called for the first time with a valid url (and authType) the callback functionality will be enabled and an authKey will be generated. Make sure you store this key. When called again with only a different url, all subsequent calls will be made to the newly specified url. The authKey will be unchanged.

When called again with another authType or resetKey set to true, a new authKey will be generated when authKey is null or omitted in the original request. This way you can, for example, automatically rotate/change the authentication keys every month. If you do specify an authKey, that key will be used instead.

{
    # Mandatory Fields
    "url": "",                      # URL to send messages to. Set this to null to disable.
    "authType": None/HMAC/ApiKey,   # Authentication type/method used in the callback messages.
    # Optional fields
    "resetKey": true/false,         # Force resetting the authentication key to a new one.
    "authKey": null                 # When resetKey is true or authType changes this key will be 
                                    # Used as the new auth key. Leave this value to null to 
                                    # automatically generate a key (depending on the AuthType).
}

{
    "authKey": "",                  # Set when a new key has been generated.
    "changed": true/false,          # True when configuration changed, false if unchanged.
    "configured": true/false,       # True when enabled, false if not enabled (or invalid)
    "success": true,
    "error": null,
    "message": null
}

POST / HTTP/1.1
Host: my.hostname.com
Content-Type: application/json
Authorization: HMAC/ApiKey ...      # Only if `AuthType` is configured (not set to None)

{
    "messageType": "",              # Message type (code).
    "message": { },                 # The message payload itself
}

Authentication

AuthType Description
None Message is sent without any authentication.
ApiKey Messages are sent with an ApiKey Authorization header. The credentials string is the exactly the same as the generated authKey.
HMAC Messages are sent with an HMAC Authorization header. The credentials string is a base64 encoded string of the HMAC hash. The HMAC (SHA256) hash is calculated using the authKey as HMAC key and one or more values from the message itself (see callback message definition). To check the HMAC (SHA256) hash, make sure you decode the authKey using base64.
OAuth2 Messages are sent with a Bearer Authorization header. When OAuth2 is used the authKey must be specified and must contain a valid uri with query string parameters. When a callback is made, the endpoint in authKey will be called using an HTTP POST with the spcified query string arguments as the form-urlencoded values. The result must be a valid JSON containing at least the access_token attribute. When a refresh_token is returned, that token will also be used when needed. An example of authKey would be:
https://example.com/token&client_id=...&client_secret=...&grant_type=client_credentials