Webhooks

CAMS follows webhook best security practice to ensure the confidentiality, integrity, and availability of the messages.

HTTPS Protocol

All webhook URLs submitted by the client must use the https protocol.

Whitelisted IP Addresses

CAMS uses static private IP addresses for it's webhooks so that client systems can use a whitelist to ignore traffic from other sources, this will also eliminate requests originating from other IP addresses.

Webhook Authentication

Webhooks are sent with an OAuth2.0 access token which can be verified using a pre-shared public key.

Unique ID

All unique messages will have a unique identifier to prevent replay attacks.

Message Order

Sometimes, due to network conditions, messages may arrive out of order. This can cause confusion in downstream systems resulting in stale data.

To remedy this, messages are transmitted with a messageTime field indicating the time the event occurred. This time can then be used by downstream systems, so that any messages received afterwards and with a time before that messageTime can be ignored.

Retry Policy

Sometimes a downstream client system is down when a critical message is sent. To account for this, all messages are sent synchronously over HTTPS, and should the response code be something other than 200 or should the request otherwise fail, the message will be sent again after a delay computed using an exponential backoff. An example is below:

Message Failure

Failure of the message occurs when all retries have been exhausted and the message has yet to be acknowledged. When this happens the message will be marked as FAILED .

Retrieve Outstanding Messages

At any time a downstream client system can submit a request for all failed or otherwise unacknowledged messages. It is generally a good practice to do this from the downstream system any time it recovers from a failure, or otherwise comes back online.

Last updated