EML Notifications

Notification API

Introduction

This is a REST APIopen in new window provided by EML, which can be used to manage your webhook(s).

  • The production API is available at: https://ws.emerchants.com.au/3.0/.
  • The test API is available at: https://beta.emerchants.com.au/3.0/.

An access token is required to use the methods in this API. See WS3 Common Authentication for further details.

REST Method Overview

The following method are available via the REST API.

  • GET /hooks
    • Get the status of all of your webhooks.
  • POST /hooks
    • Register a new webhook.
  • GET /hooks/{id}
    • Get the status of a specific webhook.
  • PATCH /hooks/{id}
    • Update configuration for a specific webhook.
  • DELETE /hooks/{id}
    • Permanently de-register and delete a webhook.
  • GET /hooks/{id}/undeliverable
    • Access failed deliveries to a specific webhook.
  • POST /hooks/{id}/undeliverable/dismiss
    • Dismiss one more failed deliveries that have now been resolved.

API Concepts

Paging

Methods on this API which support result paging have a consistent mechanism for retrieving and navigating pages.

Requests utilise query string parameters to select paging options, as demonstrated by this example:

GET /items?page_number=1&page_size=10

Responses utilise HTTP response headers, as demonstrated by this example:

HTTP/1.1 200 OK
Content-Type: application/json
X-PageSize: 10
X-TotalPages: 1
X-TotalItems: 4

[ "item1", "item2", "item3", "item4" ]

Notes

  • Valid values for page_number are between 1 and X-TotalPages inclusive.
  • We may impose an internal minimum and maximum value for page_size. Use X-PageSize on the response to see the final page size applied.
  • Methods typically use the 204 No Content status code for empty result sets.

Errors

Along with a relevant HTTP status code, all errors emitted from the API follow a consistent format:

{
    /*
     * An machine readable error code.
     * Each method in this documentation will list potential error codes for that method.
     */
    "error": "server_error",

    /*
     * An optional human readable string to describe the error.
     * This may provide more information or context.
     */
    "error_description": "An unknown error occurred."
}

Get webhook status

  • GET /hooks - Get the status of all of your webhooks.
  • GET /hooks/{id}- Get the status of a specific webhook.

These simple methods allow you to determine the current status of your webhooks. The first method returns the status of all webhooks, and the second the status of a specific webhook.

Request

When getting the status of all webhooks, paging applies to the result set. e.g.,
GET /hooks?page_number=1&page_size=10

When getting the status of a specific webhook, the request path contains the id of the desired webhook. e.g., GET /hooks/de5a6507-cb34-4c0c-a53a-5a099a9cbd2c

There is no request body for these methods.

Response

HTTP 200 - OK

The webhook status(es) were retrieved successfully.

The response format is the same for both methods, with the one difference being that GET /hooks will return an array of results, rather than a single result.

{
    /* The Id of this webhook. */
    "id": "de5a6507-cb34-4c0c-a53a-5a099a9cbd2c",

    /* The URI where messages are posted. */
    "uri": "https://your-organisation-here.com/api/webhook",

    /* 
     * The Company Id(s) which identify the EML card program(s) which this
     * webhook monitors.
     */
    "scope": [ 13902786 ],

    /* 
     * Additional filter rules which determine which transactions are sent to the webhook.
     * See the section on filter rules for more information.
     */
    "filter_spec": "*",

    /* 
     * Is the webhook enabled or disabled?
     * 
     * Disabled webhooks do not receive messages, and do not have undeliverable
     * messages stored.
     */
    "enabled": true,

    /* 
     * The reliability mode which is used by the webhook.
     * 
     * Either: "none" or "store_undeliverable"
     * See the section on reliable delivery for more information.
     */
    "reliability_mode": "store_undeliverable",

    /* 
     * The Id of the most recent non-dismissed message which we failed to deliver
     * to the webhook.
     * 
     * This value is `null` if there is no such message.
     * This value is `null` if reliability mode is not `store_undeliverable`.
     */
    "last_undeliverable": "e6acf520-865a-45e7-a48b-8c90ce241c8e",

    /* 
     * The timestamp of the most recent non-dismissed message which we failed to deliver
     * to the webhook.
     * 
     * Presented in ISO8601 format.
     * This value is `null` if there is no such message.
     * This value is `null` if reliability mode is not `store_undeliverable`.
     */
    "last_undeliverable_timestamp": "2018-04-26T10:27:38.9222315Z",

    /*
     * The identifier for the current HMAC key.
     *
     * See the Webhook Message Reference for more information on HMACs.
     * Note that "hmac_key_secret" is not included on this response.
     */
    "hmac_key_id": "b16842a9-5e7b-4f54-a3ce-112ec93dc0a9"
}

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to get the status of your webhook(s).

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}

Register a new webhook

  • POST /hooks - Register a new webhook.

This method allows you to register the configuration for a new webhook. Your configuration will be validated before being accepted. If your configuration is valid, and you elect to enable your webhook, you will begin receiving Transaction Messages from EML at the requested URI.

We will send a Ping Message when you try to enable your webhook. If you fail to respond successfully, this registration will fail with error code no_response. If your webhook is not going to be immediately available at the time of registration, you can register it as disabled, and then enable it at a later point using the PATCH /hooks/{id} method.

Request

{
    /* The URI where messages should be posted. */
    "uri": "https://your-organisation-here.com/api/webhook",

    /* 
     * The Company Id(s) which identify the EML card program(s) which this webhook
     * will monitor.
     */
    "scope": [ 13902786 ],

    /* 
     * Additional filter rules which determine which transactions are sent to the webhook.
     * See the section on filter rules for more information.
     */
    "filter_spec": "*",

    /* 
     * Register the webhook as enabled or disabled.
     * 
     * Disabled webhooks do not receive messages, and do not have undeliverable
     * messages stored.
     * 
     * Enabled webhooks must respond to a ping message on registration.
     * Disabled webhooks can be enabled at a later point in time.
     */
    "enabled": true,

    /* 
     * The reliability mode which will be used by the webhook.
     * Either: "none" or "store_undeliverable".
     * 
     * See the section on reliable delivery for more information.
     */
    "reliability_mode": "store_undeliverable",

    /*
     * An identifier, assigned by you, which will uniquely identify
     * the secret key used when calculating HMACs for each message.
     *
     * This could be an incrementing number, a cryptographic hash of your key,
     * a randomly assigned UUID, or any other identifier which works for you.
     *
     * The id must be between 1 and 64 characters. It can contain letters,
     * digits, and symbols in the ASCII character set. It can not contain
     * whitespace characters, control characters or semicolons.
     * 
     * See the Webhook Message Reference for more information on HMACs.
     */
    "hmac_key_id": "b16842a9-5e7b-4f54-a3ce-112ec93dc0a9",

    /*
     * The secret key to be used by EML when calculating HMACs for each message.
     * 
     * You must provide a 256bit hex value. (i.e., exactly 64 hex characters).
     *
     * See the Webhook Message Reference for more information on HMACs.
     */
    "hmac_key_secret": "16086f0cfcdbd2261e6d19d79b6476a8084da6062bd621b2562bc0cac1da79e4"
}

Response

HTTP 201 - Created

The registration of the webhook was successful.

{
    /* The Id of your newly registered webhook */
    "id": "de5a6507-cb34-4c0c-a53a-5a099a9cbd2c"
}

HTTP 400 - Bad Request

Your webhook configuration was invalid.

{
    "error": "no_response",
    "error_description": "Timed-out sending a ping message to: https://your-organisation-here.com/api/webhook"
}
Possible error codes:
  • invalid_request: The request was not valid JSON.
  • invalid_uri: Your webhook URI does not appear to be a valid HTTPS URI.
  • invalid_scope: Your scope was malformed.
  • invalid_filter_spec: Your filter specification was malformed.
  • invalid_enabled: You did not supply true or false for the enabled field.
  • invalid_reliability_mode: Your reliability_mode was not one of the allowable values.
  • invalid_hmac_key_id: Your hmac_key_id was malformed.
  • invalid_hmac_key_secret: Your hmac_key_secret was not a 256bit hex string.
  • no_response: You attempted to enable your webhook, but it did not respond successfully to our ping message.

HTTP 401 - Unauthorized

Your access token was invalid, or you attempted to attach a webhook to one or more of the companies which you don't have permission to access.

{
    "error": "unauthorized",
    "error_description": "You are not authorized to attach a webhook in scope: 1234"
}

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to register that webhook.

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}

Update configuration for a specific webhook

  • PATCH /hooks/{id} - Update configuration for a specific webhook.

This method allows you to update the configuration for an existing webhook. Your configuration will be validated before being accepted. If your configuration is valid, and you elect to enable your webhook, you will begin receiving Transaction Messages from EML at the requested URI.

We will send a Ping Message when you try to enable your webhook. If you fail to respond successfully, this update will fail with error code no_response.

Request

All properties on the request are optional. We will leave the configuration unchanged for properties which you omit from this request.

The request URI contains the id of the webhook to update. e.g.,
PATCH /hooks/de5a6507-cb34-4c0c-a53a-5a099a9cbd2c

{
    /* Optional: Updated URI where messages should be posted. */
    "uri": "https://your-organisation-here.com/api/webhook",

    /* 
     * Optional: Updated Company Id(s) which identify the EML card program(s) which this
     * webhook will monitor.
     */
    "scope": [ 13902786 ],

    /* 
     * Optional: Updated filter rules which determine which transactions are sent to
     * the webhook.
     * 
     * See the section on filter rules for more information.
     */
    "filter_spec": "*",

    /* 
     * Enable or disable the webhook.
     * 
     * Disabled webhooks do not receive messages, and do not have undeliverable
     * messages stored.
     * 
     * Webhooks must respond to a ping message as they are enabled.
     * Disabled webhooks can be enabled at a later point in time.
     */
    "enabled": true,

    /* 
     * The reliability mode which will be used by the webhook.
     * Either: "none" or "store_undeliverable".
     * 
     * See the section on reliable delivery for more information.
     */
    "reliability_mode": "store_undeliverable",

    /*
     * An identifier, assigned by you, which will uniquely identify
     * the secret key used when calculating HMACs for each message.
     *
     * This could be an incrementing number, a cryptographic hash of your key,
     * a randomly assigned UUID, or any other identifier which works for you.
     *
     * The id must be between 1 and 64 characters. It can contain letters,
     * digits, and symbols in the ASCII character set. It can not contain
     * whitespace characters, control characters or semicolons.
     * 
     * See the Webhook Message Reference for more information on HMACs.
     */
    "hmac_key_id": "b16842a9-5e7b-4f54-a3ce-112ec93dc0a9",

    /*
     * The secret key to be used by EML when calculating HMACs for each message.
     * 
     * You must provide a 256bit hex value. (i.e., exactly 64 hex characters).
     *
     * See the Webhook Message Reference for more information on HMACs.
     */
    "hmac_key_secret": "16086f0cfcdbd2261e6d19d79b6476a8084da6062bd621b2562bc0cac1da79e4"
}

Response

HTTP 200 - OK

The webhook was updated successfully.

HTTP 400 - Bad Request

Your webhook configuration was invalid.

{
    "error": "no_response",
    "error_description": "Timed-out sending a ping message to: https://your-organisation-here.com/api/webhook"
}
Possible error codes:
  • invalid_request: The request was not valid JSON.
  • invalid_uri: Your webhook URI does not appear to be a valid HTTPS URI.
  • invalid_scope: Your scope was malformed, or you don't have permission to attach a webhook to one or more of the companies requested.
  • invalid_filter_spec: Your filter specification was malformed.
  • invalid_enabled: You did not supply true or false for the enabled field.
  • invalid_reliability_mode: Your reliability_mode was not one of the allowable values.
  • invalid_hmac_key_id: Your hmac_key_id was malformed.
  • invalid_hmac_key_secret: Your hmac_key_secret was not a 256bit hex string.
  • no_response: You attempted to enable your webhook, but it did not respond successfully to our ping message.

HTTP 401 - Unauthorized

Your access token was invalid, or you attempted to attach a webhook to one or more of the companies which you don't have permission to access.

{
    "error": "unauthorized",
    "error_description": "You are not authorized to attach a webhook in scope: 1234"
}

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to update that webhook.

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}

Delete a Webhook

  • DELETE /hooks/{id} - Permanently de-register and delete a webhook.

Request

The request URI contains the id of the webhook to delete. e.g.,
DELETE /hooks/de5a6507-cb34-4c0c-a53a-5a099a9cbd2c.

There is no request body for this method.

Response

HTTP 204 - No Content

The webhook was deleted successfully.

HTTP 401 - Unauthorized

You aren't authorized to delete that webhook.

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to delete that webhook.

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}

Get failed deliveries

  • GET /hooks/{id}/undeliverable - Access failed deliveries to a specific webhook.

Request

This method applies paging to the result set. e.g.,
GET /hooks/de5a6507-cb34-4c0c-a53a-5a099a9cbd2c/undeliverable?page_number=1&page_size=10

There is no request body for this method.

Response

HTTP 200 - OK

Your request was processed successfully, and the messages are in the response.

[
    /*
     * Undeliverable message #1.
     * A complete message as per the "Webhook Message Reference".
     */
    {
        "id": "83646230-8f65-4060-b9d3-fd404da304f0",
        "hook_id": "de5a6507-cb34-4c0c-a53a-5a099a9cbd2c",
        "timestamp": "2018-04-24T02:43:56.4457276Z",
        "type": "transaction"
        /* etc. */
    },

    /* Undeliverable message #2 */
    {
        "id": "89c6e543-b9e3-4af6-9f77-d2a2d3cb897d"
        /* etc. */
    },

    /* Undeliverable message #3 */
    {
        "id": "f29c2adc-dcfd-490a-a0fa-d7d08f43101b"
        /* etc. */
    }

    /* etc. */
]

HTTP 204 - No Content

Your request was processed successfully, but there are no failed deliveries to retrieve. Good for you!

HTTP 400 - Bad Request

Your request was invalid.

{
    "error": "invalid_hook_id",
    "error_description": "The request URI contains an invalid hook id."
}
Possible error codes:
  • invalid_hook_id: The request URI contains an invalid hook id.

HTTP 401 - Unauthorized

You aren't authorized to view undeliverable messages for that webhook.

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to get failed deliveries.

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}

Resolve failed deliveries

  • POST /hooks/{id}/undeliverable/dismiss - Dismiss one more failed deliveries that have now been resolved.

Once you have retrieved undeliverable messages and performed your necessary handling of them, you can dismiss those messages. Dismissing a message removes it from failed deliveries. If you dismiss all undeliverable messages, we will stop sending Undeliverable Alerts to your webhook.

Request

{
    /*
     * An array of one or more Message Ids to be dismissed.
     */
    "message_ids": [
        "1dedbe31-07da-4b4a-8201-8548ebd285b1",
        "73194106-4d24-4b17-a1a8-f2d375f960f2",
        "22ae832f-3c97-42ba-8bde-ee5a003bf4e9"
    ]
}

Response

HTTP 204 - No Content

Your request was processed successfully, and the failed deliveries you specified have been dismissed.

HTTP 400 - Bad Request

Your request was invalid.

{
    "error": "invalid_message_id",
    "error_description": "One or more of your message_ids were invalid."
}
Possible error codes:
  • invalid_request: The request was not valid JSON.
  • invalid_hook_id: The request URI contains an invalid hook id.
  • invalid_message_id: One or more of your message_ids were invalid.

HTTP 401 - Unauthorized

You aren't authorized to dismiss undeliverable messages for that webhook.

HTTP 500 - Internal Server Error

Something went wrong, and we were unable to dismiss those failed deliveries.

{
    "error": "server_error",
    "error_description": "An unknown error occurred."
}