Endpoints

Our API endpoints are all exported on https://api.alcmeon.com/ and documented in our Reference documentation.

Authentication

Unless mentioned otherwise, API endpoints are authenticated via HTTP Basic Auth and you need to create a dedicated application with the right permissions for that purpose:

username: your instance_id
password: your application secret

Webhooks

A number of our APIs are based on the use of webhooks which must be exposed by our customers and will be invoked by our infrastructure.

Traffic filtering

All requests sent to these endpoints will originate from the FQDN outbound.alcmeon.com. It is important to respect the TTL associated with this DNS entry (300 seconds) to avoid any disruption that might be caused by dynamic changes in the topology of our infratructure.

Starting on March 1st 2022, we will enforce a new traffic routing policy for outbound traffic.

Signature verification

Outgoing requests contain the custom header X-Alcmeon-Webhook-Signature. These signatures are calculated as a SHA256 HMAC on the concatenation of the request path and request body using the application secret as key. The result is hexadecimal encoded and stored in the signature header.

The python code below illustrates how this signature can be re-calculated for an example of webhook url https://api.alcmeon.com/demo/subbot/start?key=value:

import hmac, hashlib, binascii
application_secret = b'88c29fe9d5477643'  # as displayed in your Alcmeon application configuration
path = b'/demo/subbot/start'  # your webhook endpoint path
body = b'the bytes of the http request body you received'
signature = hmac.new(
    application_secret,
    msg=path + b' ' + body,
    digestmod=hashlib.sha256
).hexdigest()